Architecture Overview

CORTEX uses a hybrid architecture combining a modular monolith for core business logic with microservices for specialized workloads.

System Diagram

┌──────────────────────────────────────────────────────────────────┐
│                         Clients                                   │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐                 │
│  │  Web App   │  │ Mobile App │  │ API Client │                 │
│  │ (Next.js)  │  │  (Future)  │  │            │                 │
│  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘                 │
└────────┼───────────────┼───────────────┼────────────────────────┘
         │               │               │
         └───────────────┼───────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────────────────┐
│                    API Gateway (Future)                          │
│  • Rate limiting       • Request routing                         │
│  • Authentication      • Load balancing                          │
└────────────────────────────┬─────────────────────────────────────┘
                             │
         ┌───────────────────┼───────────────────┐
         │                   │                   │
         ▼                   ▼                   ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│   Core Service  │ │ Agent Runner    │ │ Integration     │
│   (NestJS)      │ │ (Go) - Future   │ │ Workers         │
│                 │ │                 │ │ (Future)        │
│ • Auth          │ │ • AI Agents     │ │ • Webhooks      │
│ • Tenants       │ │ • Task Queue    │ │ • Sync Jobs     │
│ • Organizations │ │ • Execution     │ │ • Notifications │
│ • Users         │ │                 │ │                 │
│ • RBAC          │ │                 │ │                 │
│ • Audit         │ │                 │ │                 │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
         │                   │                   │
         └───────────────────┼───────────────────┘
                             │
         ┌───────────────────┼───────────────────┐
         │                   │                   │
         ▼                   ▼                   ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│   PostgreSQL    │ │     Redis       │ │  Azure Service  │
│   (Primary DB)  │ │   (Cache/       │ │     Bus         │
│                 │ │    Sessions)    │ │  (Message Queue)│
└─────────────────┘ └─────────────────┘ └─────────────────┘

Service Architecture

Core Service (Modular Monolith)

The core service uses a modular monolith pattern where each module is self-contained but shares the same deployment.

┌─────────────────────────────────────────────┐
│              Core Service                    │
│                                             │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐     │
│  │  Auth   │  │ Tenant  │  │  User   │     │
│  │ Module  │  │ Module  │  │ Module  │     │
│  └─────────┘  └─────────┘  └─────────┘     │
│                                             │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐     │
│  │  Org    │  │  RBAC   │  │  Audit  │     │
│  │ Module  │  │ Module  │  │ Module  │     │
│  └─────────┘  └─────────┘  └─────────┘     │
│                                             │
│  ┌───────────────────────────────────┐     │
│  │        Shared Infrastructure       │     │
│  │  (Guards, Interceptors, Filters)  │     │
│  └───────────────────────────────────┘     │
└─────────────────────────────────────────────┘

Module Dependencies

Auth ◄──────── User ◄──────── RBAC
  │              │               │
  │              ▼               │
  └──────────► Tenant ◄─────────┘
                 │
                 ▼
            Organization ◄────── Audit (observes all)

Data Flow

Request Lifecycle

1. Request arrives
        │
        ▼
2. Helmet (Security Headers)
        │
        ▼
3. CORS Check
        │
        ▼
4. Validation Pipe
        │
        ▼
5. JWT Guard (Authentication)
        │
        ▼
6. Tenant Guard (Context)
        │
        ▼
7. RBAC Guard (Authorization)
        │
        ▼
8. Controller → Service → Repository
        │
        ▼
9. Audit Interceptor (Logging)
        │
        ▼
10. Response Transform
        │
        ▼
11. Response

Design Principles

Principle	Implementation
Modularity	Each feature in its own module
Separation of Concerns	Controllers, Services, Repositories
Dependency Injection	NestJS DI container
Single Source of Truth	Prisma schema for database
Defense in Depth	Multiple security layers

Scalability Considerations

Current (Phase 1)

• Single instance deployment
• Vertical scaling
• Local session storage

Future (Phase 2+)

• Horizontal scaling with load balancer
• Redis for distributed sessions
• Read replicas for database
• Message queue for async work