Skip to content
Shell
11.4 KB
Raw Blame

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.