raheesahmed/sajicode/architect

Functional: What does it DO?
Non-Functional:
  - Expected users (100? 10K? 1M+?)
  - Latency requirements (< 100ms? < 1s?)
  - Availability target (99.9%? 99.99%?)
  - Data sensitivity (PII? Financial? Public?)
  - Compliance (GDPR, SOC2, HIPAA?)
  - Budget constraints

# ADR-001: Choose Modular Monolith Architecture
 
## Status: Accepted
 
## Context
We have a team of 5 engineers building a SaaS dashboard.
Expected users: 10K in year 1, 100K in year 3.
 
## Decision
Start with a modular monolith with clear domain boundaries.
 
## Consequences
-Faster development velocity initially
-Can extract services later if needed
-Must maintain module boundaries with linting rules
-Single deployment simplifies DevOps

src/
├── modules/
│   ├── auth/                # Auth domain
│   │   ├── routes.ts
│   │   ├── service.ts
│   │   ├── repository.ts
│   │   └── types.ts
│   ├── billing/             # Billing domain
│   │   ├── routes.ts
│   │   ├── service.ts
│   │   └── events.ts        # Publishes billing events
│   └── notifications/       # Notifications domain
│       ├── service.ts
│       └── listeners.ts     # Subscribes to billing events
├── shared/                  # Shared kernel
│   ├── database.ts
│   ├── event-bus.ts
│   └── types.ts
└── index.ts

// Event bus (in-process for monolith)
type EventHandler = (data: unknown) => Promise<void>;
class EventBus {
  private handlers = new Map<string, EventHandler[]>();
  on(event: string, handler: EventHandler) {
    const existing = this.handlers.get(event) || [];
    this.handlers.set(event, [...existing, handler]);
  }
  async emit(event: string, data: unknown) {
    const handlers = this.handlers.get(event) || [];
    await Promise.allSettled(handlers.map((h) => h(data)));
  }
}
// Usage
eventBus.on("user.created", async (data) => {
  await sendWelcomeEmail(data.email);
  await createDefaultWorkspace(data.userId);
  await trackAnalytics("signup", data);
});
await eventBus.emit("user.created", { userId: user.id, email: user.email });

// Commands (writes) — go through domain logic
class CreateOrderCommand {
  constructor(public userId: string, public items: OrderItem[]) {}
}
async function handleCreateOrder(cmd: CreateOrderCommand) {
  const order = OrderAggregate.create(cmd.userId, cmd.items);
  await orderRepository.save(order);
  await eventBus.emit("order.created", order.toEvent());
}
// Queries (reads) — optimized read models
async function getOrderSummary(userId: string) {
  return db.query(`
    SELECT o.id, o.total, o.status, COUNT(oi.id) as item_count
    FROM orders o JOIN order_items oi ON oi.order_id = o.id
    WHERE o.user_id = $1 GROUP BY o.id ORDER BY o.created_at DESC
  `, [userId]);
}

- [ ] Stateless application servers (no in-memory session state)
- [ ] Database connection pooling
- [ ] Centralized session store (Redis)
- [ ] Shared file storage (S3, not local disk)
- [ ] Load balancer with health checks
- [ ] Background job queue (BullMQ, Celery)
- [ ] CDN for static assets
- [ ] Database read replicas for read-heavy workloads

Browser Cache → CDN → Application Cache (Redis) → Database
   (hours)      (min)        (seconds)           (source of truth)

1. Optimize queries (indexes, query plans)     → handles 10x load
2. Read replicas                                → handles 50x reads
3. Connection pooling (PgBouncer)              → handles 100x connections
4. Application-level caching                    → handles 100x reads
5. Sharding (last resort)                       → handles 1000x data

1. Clarify requirements (functional + non-functional)
2. Estimate scale (users, requests/sec, storage)
3. Define API contract (endpoints, request/response)
4. Design data model (entities, relationships)
5. Draw high-level architecture (components, data flow)
6. Deep dive into critical components
7. Address bottlenecks and failure points
8. Discuss trade-offs and alternatives

Level 1: System Context — How the system fits in the world
Level 2: Container — Major technology choices (web app, API, database)
Level 3: Component — Key components within each container
Level 4: Code — Class/function level (only for critical parts)