Engineering principles, architecture decisions, and quality standards that guide HomeGrif development. A living document of our technical philosophy.
Technology Stack
We believe in using proven, mature technologies. Boring is good. Stability over hype.
Node.js
v20.x LTS
Express.js
v4.18.x
PostgreSQL
v15.x
EJS
v3.1.x
Passport.js
v0.7.x
Leaflet.js
v1.9.x
Why server-rendered? SEO, performance, simplicity. No SPA complexity, no hydration issues, no state management nightmares. The web worked fine before React.
Architecture Principles
1. Simplicity Over Cleverness
Write code that a junior developer can understand. No magic. No clever tricks. If you need a comment to explain what it does, refactor it.
2. Monolith First
One repository, one deployment, one database. Microservices are for scaling problems we don't have yet. The monolith serves 10,000 users just fine.
3. Database as Source of Truth
All state lives in PostgreSQL. No Redis caching (yet), no in-memory stores. Simple, debuggable, recoverable.
4. Progressive Enhancement
The site works without JavaScript. Forms submit. Links navigate. JS enhances, never replaces.
5. Security by Default
Helmet.js headers, CSP policies, rate limiting, input validation, parameterized queries. Security is not an afterthought.
Development Standards
The Six Rules
After a retrospective where we found 40% of commits were fixes for regressions, we established these mandatory rules:
Rule 1: No Uncommanded Changes — Never remove, simplify, or "improve" features without explicit request.
Rule 2: Read Before Edit — Always read the FULL file before making any edit. Never assume.
Rule 3: Feature Inventory Check — List all features before AND after modifications.
Rule 4: Test User Flows — Test the actual user journey, not just the edited component.
Rule 5: Environment Verification — Verify both TEST and PROD after every deployment.
Rule 6: Related Feature Check — When changing A, test everything A affects.
Pre-deployment checklist:npm run check — Runs automated feature verification on both TEST and PROD environments.
Quality Metrics
<20%
Fix commits target
14/14
Feature checks passing
v2.0.0
Stable baseline
We track the ratio of fix commits to feature commits. If fixes exceed 20% of total commits, we stop and investigate root causes.
Deployment Model
# Two-branch deployment
main → TEST (test.homegrif.com)
production → PROD (www.homegrif.com)
# Deployment flow
1. Push to main → Auto-deploys to TEST
2. Verify on TEST (npm run check:test)
3. Merge main → production
4. Push production → Auto-deploys to PROD
5. Verify on PROD (npm run check:prod)
Rollback Procedure
# Quick rollback to stable baseline
git checkout v2.0.0
git checkout -b rollback-from-broken-feature
git push origin rollback-from-broken-feature
# Update Render to deploy from rollback branch
Security Posture
Authentication — Admin: bcrypt + sessions. Users: Google OAuth via Passport.js.
Session Storage — PostgreSQL (connect-pg-simple), not memory. 24h expiry.