Architecture Overview

Architecture Overview

┌──────────────────────────────────────────────────────────┐
│                       nginx :80                          │
│   /          → frontend:3000  (Next.js 14 SSR)           │
│   /api/      → backend:8000   (FastAPI)                  │
│   /iclock/   → backend:8000   (ADMS protocol)            │
└──────────────────────────────────────────────────────────┘
           │                    │
    ┌──────┴──────┐      ┌──────┴──────┐
    │  Next.js    │      │   FastAPI   │
    │  Frontend   │      │   Backend   │
    │             │      │  /api/v1/   │
    └─────────────┘      └──────┬──────┘
                                │
              ┌─────────────────┼─────────────────┐
              │                 │                 │
       ┌──────┴──────┐  ┌───────┴──────┐  ┌──────┴──────┐
       │ PostgreSQL  │  │    Redis     │  │   Celery    │
       │    :5432    │  │    :6379     │  │  Worker+Beat│
       └─────────────┘  └─────────────┘  └─────────────┘

Tech Stack

• FastAPI 0.115 — async REST API
• SQLAlchemy 2.0 async — ORM with asyncpg driver
• Alembic — Database migrations
• Celery + Redis — Background jobs and scheduling
• Next.js 14 App Router — Frontend with SSR
• Tailwind CSS — Styling
• Zustand + TanStack Query — State management

Key Design Decisions

• Multi-tenancy: All tables have company_id. Every query filters by it.
• ADMS Push: Devices connect outbound — no polling needed.
• JWT Auth: Short-lived access tokens + refresh tokens stored in client.