# justicecanada/otto architecture

> Architecture diagram of the GitHub repository justicecanada/otto, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/justicecanada/otto
- Repository: https://github.com/justicecanada/otto

## Overview

##### Project type and purpose
- Otto is a full-stack, monolithic Django platform exposing multiple sub-applications (“apps”) (chat, laws, librarian, text_extractor) combined under one codebase.
- It serves dynamic HTML/JS front-ends, runs asynchronous workloads via Celery, and persists data in PostgreSQL (with pgbouncer). It also integrates with external AI/LLM APIs, vector stores, and provides Docker/Kubernetes deployment.

##### Main components
a. Clients & Frontend
- Web browser or automated load-test clients interacting via HTTP/HTTPS.
- Django templates + static assets (JS/CSS) delivered by Django or CDN.
b. Web Tier
- Nginx or cloud Load Balancer (in prod).
- Django application server (Gunicorn or Daphne, ASGI) serving web requests, routing via `otto/urls.py`.
- Modular Django “apps”:
– chat: real-time AI chat UI + cost estimation + persistence
– laws: XML ingestion, full-text search, vector embedding queries
– librarian: document upload, data-source management
– text_extractor: OCR/back-end pipelines
– otto (core): authentication, admin UI, feature toggles, Celery setup
c. Asynchronous Tier
- Celery workers (gevent pool) for: law ingestion, file translation, document processing, cost calculations.
- Celery Beat (django_celery_beat) for scheduled tasks (e.g., exchange rate updates, cleanup jobs).
- Celery broker (e.g., Redis or RabbitMQ configured via ENV in `.env.example`).
d. Persistence & Caching
- PostgreSQL database (django/postgres_wrapper + pgbouncer for connection pooling)
- Optional cache layer (Redis or Memcached) for session data, short-term caching, tiktoken cost estimates.
- Vector store (could be Postgres with pgvector or external—and referenced in code via `cache_tiktoken.py`, law embeddings).
e. External Services
- LLM APIs (OpenAI, Azure OpenAI, etc.) invoked from `django/chat/llm.py` and `django/laws/prompts.py`.
- Corporate Q&A library ingestion or other data sources via management commands.
- Azure Container Registry & AKS for production Docker deployment.

##### Relationships & interactions
– Client → (HTTPS) → Load Balancer/Nginx → Django (request/response)
– Django → (SQL) → PostgreSQL via pgbouncer
– Django → (Broker) → Celery tasks enqueued
– Celery Worker → (SQL) → PostgreSQL
– Celery Worker → (External API) → LLM services or vector DB
– Celery Beat → (Broker) → scheduled tasks
– Django & Celery → (Cache) → Redis/Memcached for transient data
– Django static files → CDN or Nginx

##### Architectural patterns & design principles
– Monolithic Django with clear app–level boundaries (MVC pattern).
– Asynchronous task queue for long-running or IO-bound jobs.
– Connection pooling (pgbouncer) to optimize DB throughput under load.
– DevContainer + Docker for reproducible dev environment; Dockerfile + compose for local services.
– Kubernetes deployment manifests (external repo) for production.

##### Detail orientation
– Don’t collapse the async tier into the web tier—show Celery Beat & Worker queue separately.
– Call out pgbouncer as an intermediate pool component.
– For each Django app, annotate its primary responsibilities (e.g., “chat: UI + LLM calls + cost estimation”).
– Show Dev/Prod infra only if relevant: DevContainer, Docker Compose (local), AKS cluster (prod).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients & Frontend
    Browser["Web Browser / Clients"]:::client
    Browser -->|HTTP/HTTPS| LB["Nginx / Load Balancer"]:::compute

    %% Web Tier
    LB --> Django["Django Monolith"]:::compute

    subgraph "Django Monolith"
        subgraph "Entrypoints"
            WSGI["wsgi.py"]:::compute
            ASGI["asgi.py"]:::compute
            Manage["manage.py"]:::compute
            URLsEntryp["urls.py"]:::compute
        end
        CoreOtto["Core otto app\n(auth, admin, feature toggles,\nCelery setup)"]:::compute
        ChatApp["Chat App\n(UI, LLM calls, cost estimation)"]:::compute
        LawsApp["Laws App\n(XML ingestion, search,\nvector queries)"]:::compute
        LibrarianApp["Librarian App\n(doc upload, management)"]:::compute
        TextExtApp["Text Extractor App\n(OCR, pipelines)"]:::compute

        Entrypoints --> CoreOtto
        CoreOtto --> ChatApp
        CoreOtto --> LawsApp
        CoreOtto --> LibrarianApp
        CoreOtto --> TextExtApp
    end

    Django -->|serves static| CDN["CDN / Static Assets"]:::external

    %% Async Tier
    subgraph "Async Tier"
        Beat["Celery Beat\n(scheduled tasks)"]:::compute
        Workers["Celery Workers"]:::compute
    end

    Django -->|AMQP/Redis| Workers
    Django -->|AMQP/Redis| Beat
    Beat -->|AMQP/Redis| Workers

    %% Data & Cache Tier
    subgraph "Data & Cache Tier"
        Pgbouncer["pgbouncer\n(connection pooling)"]:::storage
        Postgres["PostgreSQL"]:::storage
        Cache["Redis / Memcached"]:::storage
        VectorStore["Vector Store"]:::storage
    end

    Django -->|SQL| Pgbouncer
    Workers -->|SQL| Pgbouncer
    Pgbouncer -->|SQL| Postgres

    Django -->|cache| Cache
    Workers -->|cache| Cache

    Workers -->|vector queries| VectorStore

    %% External Services
    subgraph "External Services"
        LLM["LLM APIs"]:::external
        ACR["Azure Container Registry & AKS"]:::external
    end

    Django -->|HTTP| LLM
    Workers -->|HTTP| LLM
    Django -->|docker push| ACR

    %% Legend
    subgraph "Legend"
        Compute["Compute\n(blue)"]:::compute
        Storage["Storage\n(green)"]:::storage
        External["External\n(orange)"]:::external
    end

    %% Click Events
    click WSGI "https://github.com/justicecanada/otto/blob/main/django/otto/wsgi.py"
    click ASGI "https://github.com/justicecanada/otto/blob/main/django/otto/asgi.py"
    click Manage "https://github.com/justicecanada/otto/blob/main/django/manage.py"
    click URLsEntryp "https://github.com/justicecanada/otto/blob/main/django/otto/urls.py"
    click CoreOtto "https://github.com/justicecanada/otto/tree/main/django/otto/"
    click ChatApp "https://github.com/justicecanada/otto/tree/main/django/chat/"
    click LawsApp "https://github.com/justicecanada/otto/tree/main/django/laws/"
    click LibrarianApp "https://github.com/justicecanada/otto/tree/main/django/librarian/"
    click TextExtApp "https://github.com/justicecanada/otto/tree/main/django/text_extractor/"
    click Beat "https://github.com/justicecanada/otto/blob/main/django/otto/management/commands/update_exchange_rate.py"
    click Workers "https://github.com/justicecanada/otto/blob/main/django/otto/celery.py"
    click Pgbouncer "https://github.com/justicecanada/otto/tree/main/django/postgres_wrapper/"
    click LLM "https://github.com/justicecanada/otto/blob/main/django/chat/llm.py"

    %% Styles
    classDef compute fill:#CFE2F3,stroke:#333,stroke-width:1px
    classDef storage fill:#B7D7A8,stroke:#333,stroke-width:1px
    classDef external fill:#F4CCCC,stroke:#333,stroke-width:1px
    classDef client fill:#D9D2E9,stroke:#333,stroke-width:1px
```
