Is this a new project or refactoring existing?
│
├─ NEW PROJECT
│  │
│  ├─ Team size 1-3, MVP needed fast?
│  │  └─→ **MONOLITH** (Layered or Modular)
│  │
│  ├─ Multiple teams, different domains?
│  │  └─→ **MICROSERVICES**
│  │
│  ├─ Event-heavy, real-time processing?
│  │  └─→ **EVENT-DRIVEN ARCHITECTURE**
│  │
│  └─ Variable workload, cost-sensitive?
│     └─→ **SERVERLESS**
│
└─ REFACTORING EXISTING
   │
   ├─ Monolith too complex, teams blocked?
   │  └─→ Gradually extract to **MICROSERVICES**
   │
   ├─ Tight coupling causing issues?
   │  └─→ Introduce **EVENT-DRIVEN** patterns
   │
   └─ Cost or scaling issues?
      └─→ Migrate components to **SERVERLESS**

Layered Monolith:
├─ Presentation Layer (UI/API)
├─ Business Logic Layer
├─ Data Access Layer
└─ Database

Modular Monolith:
├─ User Module (domain-driven)
├─ Product Module
├─ Order Module
├─ Payment Module
└─ Shared Kernel

API Gateway
├─ User Service (Node.js)
├─ Product Service (Go)
├─ Order Service (Python)
├─ Payment Service (Java)
└─ Notification Service (Serverless)

Each service:
├─ Own database
├─ Independent deployment
└─ RESTful/gRPC APIs

Event Producers → Event Bus → Event Consumers
                    │
                (Kafka/RabbitMQ)
                    │
        ┌───────────┼───────────┐
        ↓           ↓           ↓
    Service A   Service B   Service C

API Gateway → Lambda Functions → Managed Services
              │
              ├─ Auth Function → Cognito
              ├─ CRUD Function → DynamoDB
              └─ Processing Function → S3

GET    /users              # List users
POST   /users              # Create user
GET    /users/{id}         # Get user
PUT    /users/{id}         # Update user (full)
PATCH  /users/{id}         # Update user (partial)
DELETE /users/{id}         # Delete user

**Response structure:**
```json
{
  "data": { /* response payload */ },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 150
  },
  "links": {
    "self": "/users?page=1",
    "next": "/users?page=2",
    "prev": null
  }
}

type User {
  id: ID!
  name: String!
  email: String!
  orders: [Order!]!
}

type Order {
  id: ID!
  total: Float!
  items: [OrderItem!]!
  user: User!
}

type Query {
  user(id: ID!): User
  users(limit: Int, offset: Int): [User!]!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
}

type Subscription {
  orderCreated: Order!
}

Frontend: Next.js 15 (App Router)
Backend: Next.js API Routes + Supabase Edge Functions
Database: PostgreSQL (Supabase)
Auth: Supabase Auth
Storage: Supabase Storage
Hosting: Vercel (frontend), Supabase (backend)

Frontend: React + Vite + TanStack Query
Backend: FastAPI (Python)
Database: PostgreSQL
Cache: Redis
Deployment: AWS ECS/Lambda + S3 + CloudFront

Backend: ASP.NET Core Web API
Database: SQL Server / CosmosDB
Frontend: Blazor / React
Deployment: Azure App Service + Azure SQL

graph TB
    User[User]
    Admin[Administrator]
    
    subgraph "System"
        API[API Gateway]
        Auth[Auth Service]
        App[Application Service]
        DB[(Database)]
    end
    
    Ext1[Payment Gateway]
    Ext2[Email Service]
    
    User -->|HTTPS| API
    Admin -->|HTTPS| API
    API --> Auth
    API --> App
    App --> DB
    App -->|REST| Ext1
    App -->|SMTP| Ext2

graph LR
    Client[Client Apps]
    Gateway[API Gateway]
    
    subgraph "Services"
        US[User Service]
        PS[Product Service]
        OS[Order Service]
        NS[Notification Service]
    end
    
    subgraph "Data"
        UDB[(User DB)]
        PDB[(Product DB)]
        ODB[(Order DB)]
    end
    
    MQ[Message Queue]
    
    Client --> Gateway
    Gateway --> US
    Gateway --> PS
    Gateway --> OS
    
    US --> UDB
    PS --> PDB
    OS --> ODB
    
    OS --> MQ
    MQ --> NS

sequenceDiagram
    participant UI as User Interface
    participant API as API Service
    participant Queue as Event Queue
    participant Process as Processing Service
    participant DB as Database
    participant Notify as Notification Service
    
    UI->>API: Create Order
    API->>DB: Save Order
    API->>Queue: Publish OrderCreated
    API-->>UI: 201 Created
    
    Queue->>Process: OrderCreated Event
    Process->>DB: Update Inventory
    Process->>Queue: Publish OrderProcessed
    
    Queue->>Notify: OrderProcessed Event
    Notify->>UI: Send Email/Push

graph TD
    subgraph "Presentation Layer"
        UI[Web UI]
        API[REST API]
    end
    
    subgraph "Business Logic Layer"
        Service[Services]
        Domain[Domain Models]
    end
    
    subgraph "Data Access Layer"
        Repo[Repositories]
        ORM[ORM/Query Builder]
    end
    
    subgraph "Infrastructure"
        DB[(Database)]
        Cache[(Cache)]
        Queue[Message Queue]
    end
    
    UI --> Service
    API --> Service
    Service --> Domain
    Service --> Repo
    Repo --> ORM
    ORM --> DB
    Service --> Cache
    Service --> Queue

Internet → WAF/CDN → Load Balancer → Private Network
                                     ├─ Web Tier (DMZ)
                                     └─ App Tier (Private)
                                        └─ Data Tier (Isolated)

Request → CDN Cache → Application Cache → Database
          (Static)    (Redis/Memcached)

src/
├── app/
│   ├── (auth)/               # Route group
│   │   ├── login/
│   │   └── register/
│   ├── (dashboard)/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   └── settings/
│   ├── api/
│   │   ├── users/route.ts
│   │   └── auth/route.ts
│   └── layout.tsx            # Root layout
├── components/
│   ├── ui/                   # shadcn components
│   ├── forms/
│   └── layouts/
├── lib/
│   ├── db/                   # Database client
│   ├── auth/                 # Auth utilities
│   └── utils.ts
├── hooks/                    # Custom React hooks
└── types/                    # TypeScript types

app/
├── api/
│   ├── __init__.py
│   ├── dependencies.py
│   └── routes/
│       ├── users.py
│       ├── products.py
│       └── orders.py
├── core/
│   ├── config.py
│   ├── security.py
│   └── database.py
├── models/                   # SQLAlchemy models
│   ├── user.py
│   └── product.py
├── schemas/                  # Pydantic schemas
│   ├── user.py
│   └── product.py
├── services/                 # Business logic
│   ├── user_service.py
│   └── order_service.py
├── main.py
└── tests/

✅ Good:
- UserController: Handle HTTP requests
- UserService: Business logic
- UserRepository: Database operations

⌠Bad:
- UserController: HTTP + business logic + database

// ✅ Good
interface IEmailService {
  sendEmail(to: string, subject: string, body: string): Promise<void>;
}

class OrderService {
  constructor(private emailService: IEmailService) {}
}

// ⌠Bad
class OrderService {
  constructor(private emailService: GmailService) {} // Concrete dependency
}