LCO DMA System Architecture¶
High-Level Overview¶
┌─────────────────────────────────────────────────────────────────────────────┐
│ CLIENT LAYER │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Browser (React 18 SPA) │ │
│ │ TypeScript + Vite + Tailwind + shadcn/ui + Zustand │ │
│ └───────────────────────────────┬─────────────────────────────────────┘ │
└──────────────────────────────────┼──────────────────────────────────────────┘
│ HTTPS
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ AZURE CLOUD │
│ │
│ ┌──────────────────────┐ ┌──────────────────────────────────────────┐ │
│ │ Azure Static Web │ │ Microsoft Entra ID │ │
│ │ Apps │ │ (JWT Provider) │ │
│ │ ───────────────── │ │ │ │
│ │ CDN + SPA Hosting │ │ • User Authentication │ │
│ └──────────────────────┘ │ • Role Claims (Reader/Contributor) │ │
│ │ • Token Validation │ │
│ └──────────────────────────────────────────┘ │
│ ▲ │
│ │ Validate JWT │
│ │ │
│ ┌───────────────────────────────────────┴───────────────────────────────┐ │
│ │ Azure Container Apps │ │
│ │ ──────────────────── │ │
│ │ FastAPI Backend (Python 3.12) │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ API Routers │ │ Schemas │ │Repositories │ │ Services │ │ │
│ │ │ (27+ files) │ │ (Pydantic) │ │ (CRUD+Batch)│ │ (Business) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └────────┬──────────────────┬────────────────────────────────┬──────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Azure Cosmos DB │ │ Azure Service │ │ Azure Blob │ │
│ │ (Serverless) │ │ Bus │ │ Storage │ │
│ │ ─────────────── │ │ ─────────────── │ │ ─────────────── │ │
│ │ • 19+ containers│ │ • Import queue │ │ • File staging │ │
│ │ • Document store│ │ • Async tasks │ │ • Excel uploads │ │
│ └─────────────────┘ └────────┬────────┘ └────────┬────────┘ │
│ ▲ │ │ │
│ │ ┌────────┴────────┐ │ │
│ │ ▼ ▼ │ │
│ │ ┌───────────────┐ ┌───────────────┐ │ │
│ │ │Azure Functions│ │Container Apps │ │ │
│ │ │(Flex Consump.)│ │ Job │ │ │
│ │ │───────────────│ │───────────────│ │ │
│ │ │ Thin wrapper │ │ Thin wrapper │◄───────────┘ │
│ │ └───────┬───────┘ └───────┬───────┘ Read files │
│ │ │ │ │
│ │ └────────┬────────┘ │
│ │ ▼ │
│ │ ┌─────────────────────────────────┐ │
│ │ │ Shared Import Processing Module│ │
│ │ │ ───────────────────────────────│ │
│ └───│ • 14 document types │ │
│ Batch │ • Handler registry │ │
│ Upsert │ • Blob download/cleanup │ │
│ │ • 100-item batch processing │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
Component Details¶
| Component | Azure Service | Purpose |
|---|---|---|
| Frontend | Azure Static Web Apps | React SPA hosting with global CDN |
| Backend API | Azure Container Apps | FastAPI with Gunicorn/Uvicorn workers |
| Import Processor | Azure Functions (Flex) OR Container Apps Job | Async document import with batch processing (14 types) |
| Shared Processing | app/services/import_processing/ |
Handler registry, blob management, Cosmos operations |
| Database | Azure Cosmos DB (Serverless) | Document storage, 19+ containers |
| Message Queue | Azure Service Bus | Async task queuing for imports |
| File Storage | Azure Blob Storage | Import file staging |
| Auth Provider | Microsoft Entra ID | User authentication, JWT tokens |
Data Flow Summary¶
- User Request: Browser → Static Web Apps → Container Apps → Cosmos DB
- Authentication: Browser ↔ Entra ID (MSAL) → JWT → API validation
- Async Import: API → Service Bus → (Functions OR Container Apps Job) → Shared Processing Module → Blob + Cosmos DB
- Real-time: Browser polls task status until completion
Import Processing Architecture¶
The import processor supports 14 document types via a shared processing module:
- Execution Environments: Azure Functions (serverless) or Container Apps Job (containerized)
- Thin Wrappers: Both environments delegate to
app/services/import_processing/ - Handler Registry: MTO, schedule, equipment, material, crew imports
- Behavioral Parity: Same logic runs regardless of execution environment