Note: Current UI is Next.js on Vercel: https://{{FRONTEND_URL}} (production app) and https://{{STAGING_FRONTEND_URL}} (staging).

Senior Architect

Guidance for architecture decisions in {{PROJECT_NAME}} and similar projects.

When to Use

• System architecture decisions (monolith vs microservices, sync vs async)
• Tech stack selection and trade-offs
• Database design and data modeling
• API design patterns (REST, GraphQL, event-driven)
• Scalability and performance architecture
• Integration patterns between services

Architecture Decision Framework

1. Understand Requirements

Functional Requirements    → What the system must do
Non-Functional Requirements → How well it must do it
├── Performance (latency, throughput)
├── Scalability (users, data volume)
├── Availability (uptime, redundancy)
├── Security (auth, encryption)
└── Maintainability (team size, deployment frequency)

2. Evaluate Trade-offs

3. Document Decisions (ADR Format)

# ADR-001: Use PostgreSQL for Campaign Data

## Status: Accepted

## Context
Campaign data has complex relationships (offers → lists → segments).
Need ACID for financial calculations (EPC, revenue).

## Decision
Use PostgreSQL with proper indexing for analytics queries.

## Consequences
+ Strong consistency for revenue calculations
+ Complex joins for analytics
- Need to manage connection pooling
- Schema migrations require planning

Common Patterns

API Layer (FastAPI)

Request → Middleware → Router → Service → Repository → Database
                ↓
           Validation (Pydantic)
                ↓
           Response

Data Pipeline (Batch)

Source (Google Sheets) → Extract → Transform → Load → PostgreSQL
                              ↓
                         Validate
                              ↓
                         Log metrics

AI Agent Architecture

User Query → Orchestrator Agent
                 ↓
         Tool Selection
         ├── SQL Tool (structured data)
         ├── Memory Tool (patterns, history)
         └── Search Tool (web, docs)
                 ↓
         Analyst Agent (reasoning)
                 ↓
         Judge Agent (validation)
                 ↓
         Response

{{PROJECT_NAME}} Tech Stack

Anti-Patterns to Avoid

1. Premature optimization - Profile first, optimize second
2. Over-engineering - Start simple, add complexity when needed
3. Distributed transactions - Use saga pattern or avoid
4. Shared mutable state - Use message passing instead
5. God classes - Split by responsibility

Quick Reference

# Check system dependencies
python -c "import sys; print(sys.version)"
pip list | grep -E "fastapi|sqlalchemy|chromadb"

# Database schema
alembic heads  # Check migration state
alembic upgrade head  # Apply migrations

# Service health
curl http://localhost:8000/health