Bootspring
HomeGet Started

Technical Architecture Workflow

Guide to designing your technical architecture including tech stack selection, system design, database schema, and API design

The Technical Architecture workflow helps you design a robust, scalable technical foundation for your product before writing code.

Overview#

PropertyValue
Phases4
TierFree
Typical Duration1-2 weeks
Best ForPre-development planning, technical decisions, team alignment

Why Architecture Matters#

Good architecture:

  • Reduces technical debt - Thoughtful decisions now prevent costly rewrites later
  • Enables velocity - The right foundations make building faster
  • Improves quality - Proper separation of concerns leads to maintainable code
  • Supports scaling - Plan for growth without over-engineering

Architecture Decision Framework#

┌─────────────────────────────────────────────────────────────────────────┐ │ ARCHITECTURE DECISION FLOW │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Requirements│───▶│ Options │───▶│ Decision │ │ │ │ Analysis │ │ Evaluation │ │ & Record │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ Questions: Criteria: Output: │ │ - What scale? - Team skills - ADR document │ │ - What budget? - Time to market - Tech stack │ │ - What team? - Scalability - System diagram │ │ - What timeline? - Cost - Implementation plan │ │ - Ecosystem │ │ │ └─────────────────────────────────────────────────────────────────────────┘

Phases#

Phase 1: Requirements Analysis (2-3 days)#

Agents: architecture-expert, business-analyst

Understand the technical requirements before making decisions.

Tasks:

  • Gather functional requirements
  • Identify non-functional requirements
  • Assess team capabilities
  • Define constraints and trade-offs
  • Document assumptions

Requirements Gathering Template:

1## Technical Requirements Analysis 2 3### Functional Requirements Summary 4[From PRD - what must the system do?] 5 6- User authentication and authorization 7- [Core feature 1] 8- [Core feature 2] 9- Data persistence and retrieval 10- Third-party integrations 11 12### Non-Functional Requirements 13 14#### Performance 15| Requirement | Target | Priority | 16|-------------|--------|----------| 17| Page load time | < 2 seconds | High | 18| API response time | < 200ms p95 | High | 19| Concurrent users | 100 initially, 10K goal | Medium | 20| Database queries | < 50ms p95 | High | 21 22#### Scalability 23| Dimension | Current Need | 12-Month Goal | 24|-----------|--------------|---------------| 25| Users | 100 | 10,000 | 26| Data volume | 1 GB | 100 GB | 27| Requests/second | 10 | 1,000 | 28| Regions | 1 | 2-3 | 29 30#### Security 31- [ ] Authentication required 32- [ ] Role-based access control 33- [ ] Data encryption (at rest, in transit) 34- [ ] Audit logging 35- [ ] Compliance requirements: [GDPR, SOC 2, etc.] 36 37#### Reliability 38| Requirement | Target | 39|-------------|--------| 40| Uptime | 99.9% | 41| Data durability | 99.999% | 42| Backup frequency | Daily | 43| Recovery time | < 4 hours | 44 45### Constraints 46 47#### Budget 48- Infrastructure: $X/month 49- Third-party services: $Y/month 50- Total: $Z/month 51 52#### Timeline 53- MVP: X weeks 54- v1.0: Y weeks 55 56#### Team 57- Developers: [count, skill levels] 58- DevOps: [count, skill levels] 59- Experience with: [technologies] 60 61### Assumptions 621. [Assumption about traffic patterns] 632. [Assumption about data growth] 643. [Assumption about team availability]

Phase 2: Tech Stack Selection (2-3 days)#

Agents: architecture-expert, backend-expert, frontend-expert

Choose technologies that match your requirements and team.

Tasks:

  • Evaluate framework options
  • Select database technology
  • Choose hosting platform
  • Select supporting services
  • Document decisions (ADRs)

Tech Stack Decision Matrix:

1## Tech Stack Evaluation 2 3### Frontend Framework 4 5| Option | Team Exp | Ecosystem | Performance | DX | Score | 6|--------|----------|-----------|-------------|-----|-------| 7| Next.js | 4/5 | 5/5 | 5/5 | 5/5 | 19/20 | 8| Remix | 2/5 | 3/5 | 5/5 | 4/5 | 14/20 | 9| SvelteKit | 1/5 | 3/5 | 5/5 | 4/5 | 13/20 | 10 11**Decision:** Next.js 12**Reasoning:** Team experience, mature ecosystem, Vercel integration 13 14### Database 15 16| Option | Use Case Fit | Scalability | Cost | Ops Burden | Score | 17|--------|--------------|-------------|------|------------|-------| 18| PostgreSQL (Neon) | 5/5 | 4/5 | 5/5 | 5/5 | 19/20 | 19| PostgreSQL (RDS) | 5/5 | 5/5 | 3/5 | 3/5 | 16/20 | 20| MongoDB (Atlas) | 3/5 | 5/5 | 3/5 | 4/5 | 15/20 | 21| PlanetScale (MySQL) | 4/5 | 5/5 | 4/5 | 5/5 | 18/20 | 22 23**Decision:** PostgreSQL (Neon) 24**Reasoning:** Relational data, serverless scaling, generous free tier 25 26### Hosting Platform 27 28| Option | Ease of Use | Cost | Features | Lock-in | Score | 29|--------|-------------|------|----------|---------|-------| 30| Vercel | 5/5 | 4/5 | 5/5 | 3/5 | 17/20 | 31| Railway | 4/5 | 4/5 | 4/5 | 4/5 | 16/20 | 32| Render | 4/5 | 5/5 | 3/5 | 5/5 | 17/20 | 33| AWS | 3/5 | 3/5 | 5/5 | 3/5 | 14/20 | 34 35**Decision:** Vercel 36**Reasoning:** Next.js optimization, zero-config deploys, great DX

Architecture Decision Record (ADR) Template:

1# ADR-001: Database Selection 2 3## Status 4Accepted 5 6## Context 7We need to choose a database for our SaaS application. The application 8will store user data, projects, and activity logs. We expect to start 9with 100 users and grow to 10,000 within 12 months. 10 11## Decision 12We will use PostgreSQL hosted on Neon. 13 14## Consequences 15 16### Positive 17- Strong relational model fits our data 18- Serverless scaling reduces ops burden 19- Generous free tier for early stage 20- Prisma ORM support 21- Easy to migrate to other Postgres hosts 22 23### Negative 24- Limited by Neon's feature set 25- Potential cold starts on serverless 26- Need to manage connection pooling 27 28### Neutral 29- Team has PostgreSQL experience 30- Industry standard choice 31 32## Alternatives Considered 33 34### MongoDB Atlas 35Rejected because our data is relational and we'd lose type safety benefits. 36 37### PlanetScale 38Strong option, but PostgreSQL ecosystem is more familiar to the team. 39 40### Self-hosted PostgreSQL 41Too much ops burden for current team size.

Phase 3: System Design (3-5 days)#

Agents: architecture-expert, backend-expert

Design the system architecture and component interactions.

Tasks:

  • Create system architecture diagram
  • Define service boundaries
  • Design data flow
  • Plan API structure
  • Document integration points

System Architecture Diagram:

┌─────────────────────────────────────────────────────────────────────────┐ │ SYSTEM ARCHITECTURE │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ CLIENT LAYER │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ Web App │ │ Mobile Web │ │ API │ │ │ │ │ │ (Next.js) │ │ (Responsive)│ │ Consumers │ │ │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ └─────────┼────────────────┼────────────────┼──────────────────────┘ │ │ │ │ │ │ │ └────────────────┼────────────────┘ │ │ │ │ │ ┌──────────────────────────▼───────────────────────────────────────┐ │ │ │ API LAYER (Vercel) │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ │ │ Next.js API Routes │ │ │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ │ │ Auth │ │ Users │ │Projects │ │Webhooks │ │ │ │ │ │ │ │ Routes │ │ Routes │ │ Routes │ │ Routes │ │ │ │ │ │ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │ │ │ │ └───────┼────────────┼────────────┼────────────┼─────────────┘ │ │ │ └──────────┼────────────┼────────────┼────────────┼───────────────┘ │ │ │ │ │ │ │ │ ┌──────────▼────────────▼────────────▼────────────▼───────────────┐ │ │ │ SERVICE LAYER │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │ Auth │ │ User │ │ Project │ │ Payment │ │ │ │ │ │ Service │ │ Service │ │ Service │ │ Service │ │ │ │ │ │ (Clerk) │ │ │ │ │ │ (Stripe) │ │ │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────▼──────────────────────────────────────┐ │ │ │ DATA LAYER │ │ │ │ ┌──────────────────────┐ ┌──────────────────────┐ │ │ │ │ │ PostgreSQL │ │ Redis │ │ │ │ │ │ (Neon) │ │ (Upstash) │ │ │ │ │ │ - Users │ │ - Sessions │ │ │ │ │ │ - Projects │ │ - Cache │ │ │ │ │ │ - Activity │ │ - Rate limits │ │ │ │ │ └──────────────────────┘ └──────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ EXTERNAL SERVICES │ │ │ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ │ │ │ │ Clerk │ │ Stripe │ │ Resend │ │ Sentry │ │PostHog │ │ │ │ │ │ (Auth) │ │(Payment│ │(Email) │ │(Errors)│ │(Analyt)│ │ │ │ │ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘

Data Flow Diagram:

┌─────────────────────────────────────────────────────────────────────────┐ │ USER AUTHENTICATION FLOW │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ User Frontend API Clerk Database │ │ │ │ │ │ │ │ │ │──Sign In────▶│ │ │ │ │ │ │ │──POST /auth/signin────────▶│ │ │ │ │ │ │ │──Verify─────▶│ │ │ │ │ │ │◀─────────────│ │ │ │ │◀──Session Token─────────────│ │ │ │ │◀──Redirect────│ │ │ │ │ │ │ │ │ │ │ │ │ │──Access Page─▶│ │ │ │ │ │ │ │──GET /api/user (w/ token)─▶│ │ │ │ │ │ │──Verify Token│ │ │ │ │ │ │◀─────────────│ │ │ │ │ │ │──Query User──────────────▶│ │ │ │ │ │◀──User Data─────────────────│ │ │ │ │◀──User Data──│ │ │ │ │ │◀──Render──────│ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────────────┘

Phase 4: Database & API Design (3-5 days)#

Agents: database-expert, api-expert

Design the data model and API contracts.

Tasks:

  • Design database schema
  • Define entity relationships
  • Design API endpoints
  • Document API contracts
  • Plan for data migrations

Database Schema Design:

1// prisma/schema.prisma 2 3// =========================================== 4// Core Entities 5// =========================================== 6 7model User { 8 id String @id @default(cuid()) 9 externalId String @unique // Clerk user ID 10 email String @unique 11 name String? 12 avatarUrl String? 13 createdAt DateTime @default(now()) 14 updatedAt DateTime @updatedAt 15 16 // Relations 17 memberships OrganizationMember[] 18 createdProjects Project[] @relation("ProjectCreator") 19 activities Activity[] 20 21 @@index([externalId]) 22} 23 24model Organization { 25 id String @id @default(cuid()) 26 name String 27 slug String @unique 28 logoUrl String? 29 createdAt DateTime @default(now()) 30 updatedAt DateTime @updatedAt 31 32 // Relations 33 members OrganizationMember[] 34 projects Project[] 35 subscription Subscription? 36 37 @@index([slug]) 38} 39 40model OrganizationMember { 41 id String @id @default(cuid()) 42 role Role @default(MEMBER) 43 createdAt DateTime @default(now()) 44 45 // Relations 46 userId String 47 user User @relation(fields: [userId], references: [id], onDelete: Cascade) 48 organizationId String 49 organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade) 50 51 @@unique([userId, organizationId]) 52 @@index([organizationId]) 53} 54 55enum Role { 56 OWNER 57 ADMIN 58 MEMBER 59 VIEWER 60} 61 62// =========================================== 63// Feature Entities 64// =========================================== 65 66model Project { 67 id String @id @default(cuid()) 68 name String 69 description String? 70 status ProjectStatus @default(ACTIVE) 71 createdAt DateTime @default(now()) 72 updatedAt DateTime @updatedAt 73 74 // Relations 75 organizationId String 76 organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade) 77 creatorId String 78 creator User @relation("ProjectCreator", fields: [creatorId], references: [id]) 79 activities Activity[] 80 81 @@index([organizationId]) 82 @@index([creatorId]) 83} 84 85enum ProjectStatus { 86 ACTIVE 87 ARCHIVED 88 DELETED 89} 90 91// =========================================== 92// System Entities 93// =========================================== 94 95model Activity { 96 id String @id @default(cuid()) 97 type String // 'project.created', 'project.updated', etc. 98 metadata Json? 99 createdAt DateTime @default(now()) 100 101 // Relations 102 userId String? 103 user User? @relation(fields: [userId], references: [id], onDelete: SetNull) 104 projectId String? 105 project Project? @relation(fields: [projectId], references: [id], onDelete: SetNull) 106 107 @@index([userId]) 108 @@index([projectId]) 109 @@index([createdAt]) 110} 111 112model Subscription { 113 id String @id @default(cuid()) 114 stripeCustomerId String @unique 115 stripeSubscriptionId String? @unique 116 stripePriceId String? 117 status String @default("inactive") 118 currentPeriodEnd DateTime? 119 cancelAtPeriodEnd Boolean @default(false) 120 createdAt DateTime @default(now()) 121 updatedAt DateTime @updatedAt 122 123 // Relations 124 organizationId String @unique 125 organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade) 126}

API Design:

1## API Endpoints 2 3### Authentication 4Handled by Clerk - no custom endpoints needed. 5 6### Users 7| Method | Endpoint | Description | 8|--------|----------|-------------| 9| GET | /api/users/me | Get current user profile | 10| PATCH | /api/users/me | Update current user profile | 11| DELETE | /api/users/me | Delete account (GDPR) | 12 13### Organizations 14| Method | Endpoint | Description | 15|--------|----------|-------------| 16| GET | /api/organizations | List user's organizations | 17| POST | /api/organizations | Create organization | 18| GET | /api/organizations/:id | Get organization details | 19| PATCH | /api/organizations/:id | Update organization | 20| DELETE | /api/organizations/:id | Delete organization | 21 22### Organization Members 23| Method | Endpoint | Description | 24|--------|----------|-------------| 25| GET | /api/organizations/:id/members | List members | 26| POST | /api/organizations/:id/members | Invite member | 27| PATCH | /api/organizations/:id/members/:memberId | Update role | 28| DELETE | /api/organizations/:id/members/:memberId | Remove member | 29 30### Projects 31| Method | Endpoint | Description | 32|--------|----------|-------------| 33| GET | /api/organizations/:orgId/projects | List projects | 34| POST | /api/organizations/:orgId/projects | Create project | 35| GET | /api/projects/:id | Get project details | 36| PATCH | /api/projects/:id | Update project | 37| DELETE | /api/projects/:id | Archive project | 38 39### Webhooks 40| Endpoint | Source | Description | 41|----------|--------|-------------| 42| POST /api/webhooks/clerk | Clerk | User events | 43| POST /api/webhooks/stripe | Stripe | Payment events |

API Response Format:

1// lib/api/types.ts 2 3// Success response 4interface ApiResponse<T> { 5 data: T; 6 meta?: { 7 page?: number; 8 perPage?: number; 9 total?: number; 10 }; 11} 12 13// Error response 14interface ApiError { 15 error: { 16 code: string; 17 message: string; 18 details?: Record<string, string[]>; 19 }; 20} 21 22// Example responses 23 24// GET /api/organizations/:id/projects 25{ 26 "data": [ 27 { 28 "id": "proj_123", 29 "name": "My Project", 30 "status": "ACTIVE", 31 "createdAt": "2024-01-15T10:00:00Z" 32 } 33 ], 34 "meta": { 35 "page": 1, 36 "perPage": 20, 37 "total": 45 38 } 39} 40 41// POST /api/organizations/:id/projects (validation error) 42{ 43 "error": { 44 "code": "VALIDATION_ERROR", 45 "message": "Invalid input", 46 "details": { 47 "name": ["Name is required", "Name must be at least 2 characters"] 48 } 49 } 50}

Starting the Workflow#

1# Start architecture workflow 2bootspring workflow start seed-architecture 3 4# Generate architecture diagram 5bootspring seed architecture diagram 6 7# Create ADR 8bootspring seed architecture adr create "Database Selection" 9 10# Generate schema from design 11bootspring seed architecture schema generate

Deliverables#

A successful Technical Architecture workflow produces:

  • Requirements analysis document
  • Tech stack decision matrix
  • Architecture Decision Records (ADRs)
  • System architecture diagram
  • Data flow diagrams
  • Database schema (Prisma)
  • API specification
  • Implementation roadmap

Best Practices#

  1. Document decisions - Use ADRs to record why, not just what
  2. Start simple - You can always add complexity later
  3. Optimize for change - Requirements will evolve
  4. Consider ops burden - Choose managed services early on
  5. Plan for observability - Build in logging, metrics, tracing
  6. Design for failure - Assume things will go wrong

Common Pitfalls#

  • Over-engineering for scale you don't have
  • Choosing unfamiliar tech without buffer time
  • Not documenting architectural decisions
  • Ignoring operational complexity
  • Designing in isolation without team input

Related Workflows#