jmsktm/architect

ID8ARCHITECT - Technical Design Engine

Purpose

Transform validated ideas into concrete, buildable technical plans. Architecture should enable velocity, not slow it down.

Philosophy: Boring technology, managed services, ship fast, iterate often.

---

When to Use

• Project has a BUILD verdict from scout
• User needs to design system architecture
• User asks "how should I build this?"
• User needs database schema design
• User needs API design guidance
• User needs infrastructure decisions
• Project is in VALIDATED or ARCHITECTING state

---

Commands

/architect <project-slug>

Run full architecture design for a validated project.

Process:

1. REQUIREMENTS - Extract from validation report
2. ARCHITECTURE - Design system components
3. STACK - Select technologies
4. DATA - Model the database
5. API - Design interfaces
6. INFRASTRUCTURE - Plan deployment
7. ROADMAP - Phase the implementation

/architect stack <requirements>

Get stack recommendations for specific requirements.

/architect schema <domain-description>

Design database schema for a domain.

/architect api <resource-description>

Design API endpoints for a resource.

---

Design Philosophy

Solo Builder Optimization

This is NOT enterprise architecture. Optimize for:

| Principle | Application | |-----------|-------------| | Speed over Scale | Launch fast, optimize later | | Boring Technology | Use proven, well-documented tools | | Managed Services | Let providers handle infrastructure | | Monolith First | No microservices until proven need | | Convention over Configuration | Use framework defaults | | Delete Before Build | Question every feature |

Technology Preferences

Preferred Stack (default unless reason to deviate):

| Layer | Technology | Why | |-------|------------|-----| | Frontend | Next.js 14+ (App Router) | React + SSR + API routes | | Styling | Tailwind CSS + shadcn/ui | Fast, consistent, accessible | | Backend | Next.js API routes / Edge | Same deploy, simple | | Database | Supabase (PostgreSQL) | Managed, real-time, auth included | | Auth | Supabase Auth | Integrated, handles edge cases | | Storage | Supabase Storage | Integrated with auth | | Hosting | Vercel | Zero-config Next.js deploy | | Monitoring | Vercel Analytics + Sentry | Essential observability |

When to Deviate:

• Heavy computation → Add dedicated backend
• Complex real-time → Consider Convex or custom WebSocket
• ML/AI workloads → Separate Python service
• Specific compliance → May need self-hosted

---

Process Detail

Phase 1: REQUIREMENTS

Extract from validation report:

• Core problem being solved
• Target user persona
• Must-have features (max 5 for MVP)
• Success metrics
• Constraints (budget, timeline, skills)

Output:

## Requirements Summary

### Problem
{What are we solving}

### User
{Who is this for}

### MVP Features
1. {Feature 1}
2. {Feature 2}
3. {Feature 3}

### Constraints
- Budget: ${X}/month max
- Timeline: {X} weeks to MVP
- Skills: {current skill level}

Phase 2: ARCHITECTURE

Design high-level system:

┌─────────────────────────────────────────────────┐
│                    CLIENT                        │
│            (Next.js App Router)                 │
└─────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│                 API LAYER                        │
│         (Next.js API Routes / Edge)             │
└─────────────────────────────────────────────────┘
                        │
            ┌───────────┼───────────┐
            ▼           ▼           ▼
       ┌────────┐  ┌────────┐  ┌────────┐
       │ Auth   │  │Database│  │Storage │
       │(Supa)  │  │(Supa)  │  │(Supa)  │
       └────────┘  └────────┘  └────────┘

Decisions to Document:

• Client rendering strategy (SSR/SSG/CSR)
• State management approach
• API design (REST vs tRPC)
• Authentication flow
• Error handling strategy

Phase 3: STACK

Use the frameworks/stack-selection.md decision matrix.

For each technology choice:

1. State the requirement
2. List 2-3 options
3. Pick one with brief rationale
4. Document trade-offs

Phase 4: DATA

Design database schema using frameworks/database-patterns.md.

Key Tables to Define:

• Core domain entities
• User/auth tables (if not using Supabase defaults)
• Relationship tables
• Audit/logging tables

For Each Table:

• Fields with types
• Primary keys
• Foreign keys
• Indexes
• RLS policies (Supabase)

Phase 5: API

Design API using frameworks/api-design.md.

For Each Endpoint:

• Method + Path
• Request body/params
• Response shape
• Error cases
• Auth requirements

Phase 6: INFRASTRUCTURE

Plan deployment using frameworks/infrastructure.md.

Define:

• Hosting configuration
• Environment management
• CI/CD pipeline
• Monitoring setup
• Backup strategy

Phase 7: ROADMAP

Create phased implementation plan using templates/build-roadmap.md.

Phases:

• MVP (Weeks 1-4): Core loop, basic auth, essential features
• V1 (Weeks 5-8): Polish, secondary features, onboarding
• V2 (Weeks 9-12): Growth features, integrations, optimization

---

Framework References

System Design

frameworks/system-design.md - Component patterns, coupling, boundaries

Stack Selection

frameworks/stack-selection.md - Technology decision matrix

Database Patterns

frameworks/database-patterns.md - Schema design, Supabase patterns

API Design

frameworks/api-design.md - REST patterns, error handling, versioning

Infrastructure

frameworks/infrastructure.md - Deploy, CI/CD, monitoring

---

Output Templates

Architecture Document

templates/architecture-doc.md - Full technical specification

Build Roadmap

templates/build-roadmap.md - Phased implementation plan

---

Tool Integration

Subagents

backend-architect:

• System design decisions
• API contract design
• Integration patterns

database-architect:

• Schema design
• Query optimization
• Data modeling

Skills

database-design:

• Supabase-specific patterns
• RLS policy design
• Migration strategies

supabase-expert:

• Edge functions
• Real-time subscriptions
• Storage configuration

---

Handoff

After completing architecture:

1. Save outputs:

   • Architecture doc → docs/ARCHITECTURE.md in project
   • Build roadmap → docs/BUILD_ROADMAP.md in project

2. Log to tracker:

   /tracker log {project-slug} "ARCHITECT: Architecture complete. Stack: {stack}. MVP scope: {features}. Estimated timeline: {weeks} weeks."
   

3. Update state:

   /tracker update {project-slug} BUILDING
   

4. Next steps:

   • Proceed to 11-stage pipeline Stage 4 (Foundation Pour)
   • Begin scaffolding based on architecture doc

---

Anti-Patterns

Avoid These

| Anti-Pattern | Why Bad | Do Instead | |--------------|---------|------------| | Microservices from start | Complexity overhead | Monolith first | | Custom auth | Security risk, time sink | Use Supabase Auth | | Premature optimization | Waste of time | Ship, measure, optimize | | Complex state management | Redux overkill for most apps | Zustand or Context | | Self-hosted everything | Ops overhead | Managed services | | GraphQL for simple CRUD | Overhead without benefit | REST or tRPC |

Right-Size Your Architecture

Simple CRUD app → Next.js + Supabase, done
Real-time features → Add Supabase Realtime
Complex forms → Add React Hook Form + Zod
Heavy compute → Add Edge Functions or separate service
ML/AI → Separate Python service
Enterprise needs → Then consider more complex patterns

---

Quality Checks

Before signing off on architecture:

• [ ] Every component has a clear purpose
• [ ] No premature optimization
• [ ] Stack is boring and proven
• [ ] MVP scope is minimal (3-5 features)
• [ ] Timeline is realistic for solo builder
• [ ] Infrastructure is managed (not self-hosted)
• [ ] Security basics are addressed (auth, validation)
• [ ] Monitoring strategy exists