Architect

Architect — System Design

Structure the system before building it. Good architecture makes everything easier. Bad architecture makes everything a rewrite.

Step 0: Understand Constraints

Before designing, answer:

1. Scale — 100 users or 100,000? Determines everything.
2. Team size — Solo founder or 10 engineers? Simpler systems for smaller teams.
3. Budget — Bootstrapped or funded? Managed services vs self-hosted.
4. Timeline — MVP in 2 weeks or v1 in 3 months?
5. Compliance — HIPAA, SOC 2, GDPR? Constrains architecture choices.

Architecture Patterns

Default: Monolith until it hurts. Premature microservices is the #1 architecture mistake.

Database Selection

Rules:

• Start with Postgres. Add specialized databases only when Postgres can't do the job.
• Managed always (Supabase, Neon, RDS). Don't manage your own database.
• One database engine until you have a DBA. Two databases = two problems.

Project Structure

Detect the stack first. Check package.json, go.mod, Gemfile, pyproject.toml, pom.xml, or Cargo.toml before recommending a structure. Apply the principles below to whatever stack the project uses.

Universal rules — apply to every stack:

• Feature code stays together. Don't scatter a feature across 8 directories.
• Services contain business logic. Routes are thin — validate, call service, respond.
• One service per domain, not one file per function.

Example: TypeScript / Next.js

src/
├── app/                    # Next.js app router — pages and layouts
│   ├── (auth)/             # Route groups for auth pages
│   ├── (dashboard)/        # Route groups for app pages
│   └── api/                # API routes
├── lib/                    # Shared utilities, config, constants
│   ├── db/                 # Database client, schema, migrations
│   ├── auth/               # Auth config and helpers
│   └── utils/              # Pure utility functions
├── services/               # Business logic — one file per domain
├── components/             # React components
│   ├── ui/                 # Primitives (button, input, card)
│   └── features/           # Feature-specific composites
└── types/                  # Shared TypeScript types

Example: Python / FastAPI

src/
├── api/
│   ├── v1/                 # Versioned endpoints
│   └── deps.py             # Shared dependencies (auth, db session)
├── core/                   # Config, security, constants
├── models/                 # ORM models
├── schemas/                # Request/response schemas
├── services/               # Business logic — one file per domain
├── repositories/           # Data access layer
└── tests/
    ├── unit/
    └── integration/

Example: Go

cmd/
├── api/                    # Application entrypoint
internal/
├── handler/                # HTTP handlers (thin — validate + call service)
├── service/                # Business logic
├── repository/             # DB access layer
├── model/                  # Domain types
└── config/                 # Config loading
pkg/                        # Shared, importable packages

Example: Ruby on Rails

app/
├── controllers/            # Thin — params, call service, render
├── models/                 # ActiveRecord + domain logic
├── services/               # Complex business logic extracted from models
├── views/                  # Templates or JSON serializers
└── jobs/                   # Background jobs (Sidekiq)
config/
db/
├── migrate/                # Migrations
└── schema.rb

For other stacks (Java/Spring, .NET, Rust, Elixir): apply the same principle — thin routes, services for business logic, repositories for data access, tests alongside the code they test.

API Design

Caching Strategy

Rules:

• Cache reads, not writes. Invalidate on mutation.
• Start with no cache. Add caching when you measure a bottleneck.
• Every cache needs an invalidation strategy. "TTL and hope" works until it doesn't.

Scaling Checklist

Only optimize when you hit the problem:

The best architecture is the simplest one that handles your current scale + 10×.