ARCHITECTURE.md
Reusable Architectural Patterns
Good architecture is frozen decisions. This file is the freezer.
How to Use This File
- Starting a new project? Scan for relevant patterns.
- Find a pattern that fits? Adapt it, don't adopt blindly.
- Discover a new pattern? Add it here.
Web App Patterns
The Classic SPA
When to use: Interactive app, authenticated users, complex state.
┌─────────────────────────────────────────────────┐
│ Frontend (React/Vue) │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Pages/ │ │ State │ │ API │ │
│ │ Routes │ │ Store │ │ Client │ │
│ └───────────┘ └───────────┘ └───────────┘ │
└───────────────────────┬─────────────────────────┘
│ REST/GraphQL
▼
┌─────────────────────────────────────────────────┐
│ Backend (Node/Python) │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Routes/ │ │ Business │ │ Data │ │
│ │ Controllers│ │ Logic │ │ Access │ │
│ └───────────┘ └───────────┘ └───────────┘ │
└───────────────────────┬─────────────────────────┘
│
▼
┌───────────┐
│ Database │
└───────────┘
Key decisions:
- State management: Zustand (simple), Redux (complex), React Query (server state)
- API: REST for CRUD-heavy, GraphQL for flexible queries
- Auth: JWT in httpOnly cookie, refresh token rotation
The Serverless App
When to use: Variable load, cost-sensitive, event-driven.
┌──────────────────────────────────────────────────────┐
│ Frontend (Static) │
│ Hosted on CDN (Vercel/Netlify) │
└───────────────────────┬──────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────┐
│ API Layer │
│ Serverless Functions (Edge/Lambda) │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ /api/x │ │ /api/y │ │ /api/z │ │
│ └─────────┘ └─────────┘ └─────────┘ │
└───────────────────────┬──────────────────────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Database │ │ Storage │ │ 3rd Party│
│ (Supabase│ │ (S3/R2) │ │ APIs │
│ /Neon) │ │ │ │ │
└──────────┘ └──────────┘ └──────────┘
Key decisions:
- Cold starts matter for user-facing functions
- Edge functions for auth/redirects
- Managed database (Supabase, PlanetScale, Neon)
- Watch for vendor lock-in
The AI-Augmented App
When to use: LLM integration, generation features, semantic search.
┌─────────────────────────────────────────────────┐
│ Frontend │
│ ┌─────────────────────────────────────────┐ │
│ │ Streaming Response Handler │ │
│ │ Optimistic UI for generation │ │
│ └─────────────────────────────────────────┘ │
└───────────────────────┬─────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ Backend │
│ ┌───────────────┐ ┌───────────────────────┐ │
│ │ Prompt │ │ Context Management │ │
│ │ Engineering │ │ (RAG, embeddings) │ │
│ └───────────────┘ └───────────────────────┘ │
└───────┬─────────────────────┬───────────────────┘
│ │
▼ ▼
┌───────────┐ ┌───────────────┐
│ LLM API │ │ Vector DB │
│ (Claude, │ │ (Pinecone, │
│ OpenAI) │ │ Supabase) │
└───────────┘ └───────────────┘
Key decisions:
- Streaming responses for UX (SSE or WebSocket)
- Prompt versioning (track what works)
- Rate limiting and cost controls
- Fallbacks for API failures
Data Patterns
The Document Store Pattern
When to use: Flexible schema, nested data, rapid iteration.
// User with embedded preferences and history
{
id: "user_123",
email: "[email protected]",
profile: {
name: "Eddie",
avatar: "...",
},
preferences: {
theme: "dark",
notifications: true
},
recentProjects: [
{ id: "proj_1", name: "ID8Composer", lastOpened: "..." }
]
}
Good for: User profiles, content with metadata, config. Bad for: Highly relational data, complex queries across entities.
The Event Sourcing Pattern
When to use: Need full history, undo/redo, audit trail.
Events (immutable log):
┌────────────────────────────────────────────┐
│ { type: "CREATED", data: {...}, ts: T1 } │
│ { type: "UPDATED", data: {...}, ts: T2 } │
│ { type: "RENAMED", data: {...}, ts: T3 } │
└────────────────────────────────────────────┘
│
▼ (replay/project)
┌───────────┐
│ Current │
│ State │
└───────────┘
Good for: Version control, collaborative editing, compliance. Bad for: Simple CRUD, high-frequency updates.
Note: ID8Composer uses this for semantic versioning.
The CQRS Pattern
When to use: Read and write patterns are very different.
Commands (writes): Queries (reads):
┌────────────────┐ ┌────────────────┐
│ Create, Update │ │ List, Search │
│ Delete │ │ Aggregate │
└───────┬────────┘ └───────┬────────┘
│ │
▼ ▼
┌──────────┐ (sync/event) ┌──────────────┐
│ Write DB │ ──────────────▶ │ Read DB/View │
└──────────┘ └──────────────┘
Good for: High-read applications, complex reporting, search. Bad for: Simple apps, strong consistency requirements.
Frontend Component Patterns
Container/Presenter
Separate data fetching from display.
// Container (handles data)
function ProjectListContainer() {
const { data, loading } = useProjects();
return <ProjectList projects={data} loading={loading} />;
}
// Presenter (handles display)
function ProjectList({ projects, loading }) {
if (loading) return <Skeleton />;
return projects.map(p => <ProjectCard key={p.id} {...p} />);
}
Compound Components
Components that work together, share implicit state.
// Usage
<Tabs>
<Tabs.List>
<Tabs.Tab>One</Tabs.Tab>
<Tabs.Tab>Two</Tabs.Tab>
</Tabs.List>
<Tabs.Panels>
<Tabs.Panel>Content 1</Tabs.Panel>
<Tabs.Panel>Content 2</Tabs.Panel>
</Tabs.Panels>
</Tabs>
Good for: Complex UI components (tabs, accordions, dropdowns).
Render Props / Hooks
Share logic without sharing UI.
// Hook approach (preferred)
function useToggle(initial = false) {
const [on, setOn] = useState(initial);
const toggle = () => setOn(!on);
return { on, toggle, setOn };
}
// Usage
function Component() {
const { on, toggle } = useToggle();
return <button onClick={toggle}>{on ? 'ON' : 'OFF'}</button>;
}
API Patterns
RESTful Resource Pattern
GET /projects → List all
GET /projects/:id → Get one
POST /projects → Create
PATCH /projects/:id → Update
DELETE /projects/:id → Delete
Nested resources:
GET /projects/:id/versions
POST /projects/:id/versions
Action-Based API Pattern
When REST doesn't fit (complex operations):
POST /projects/:id/actions/publish
POST /projects/:id/actions/duplicate
POST /projects/:id/actions/export
Adding New Patterns
When you discover/create a pattern:
### [Pattern Name]
**When to use**: [Situations where this fits]
[Diagram or code example]
**Good for**: [Strengths]
**Bad for**: [Weaknesses]
**Project**: [Where this was used]
Remember
"Patterns are not rules. They're starting points."
Adapt patterns to your context. The best architecture is the one that ships and can evolve.