# codaqui/tutor architecture

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

- Interactive diagram: https://gitdiagram.com/codaqui/tutor
- Repository: https://github.com/codaqui/tutor

## Overview

##### Project Type and Purpose
- Full-stack, multi-service intranet application.
- Core web interface built on Django (Python) with multiple reusable “apps” (modules).
- Supplementary microservices for WhatsApp integration (Node/Express + Baileys & FastAPI), AI (Ollama), reverse-proxy (NGINX), and databases (Postgres, MongoDB).

##### File Structure
Top-level containers:
– Django monolith (“codaqui” project folder) orchestrating the intranet logic.
– Additional services:
- whatsapp_api (Node.js + Express + Baileys)
- whatsapp_app (Python + FastAPI business logic + Ollama API calls)
- ollama (AI model runner)
- nginx (reverse proxy configuration)
– Configuration files: Dockerfile, docker-compose.yml (dev & prod), env examples, GitHub workflows.
Inside the Django monolith:
- Six Django “apps”: core, users, student, wallet, github_service, whatsapp_messages.
- Shared templates directory.
- URL routing modules, models, views, forms, tests in each app.
- Standard MVC pattern (Models → Views → Templates).

##### Extract Insights from README
– External user → CloudFlare → NGINX → Django app
– Django app → Postgres
– Django (whatsapp_messages) → FastAPI whatsapp_app → Ollama (ACL)
– FastAPI → whatsapp_api (pooling messages via Baileys) → WhatsApp and MongoDB session store
- Features: GitHub OAuth & team membership validation, student profile, wallet/points ledger, GitHub issue management.

##### Main Components & Interactions
a. Components (group by container/service):
1. Client / Web Browser
2. NGINX (reverse proxy)
3. Django Intranet Service
– Sub-components: core, users, student, wallet, github_service, whatsapp_messages
4. Postgres Database
5. GitHub REST API (external)
6. whatsapp_app (FastAPI)
7. Ollama (local AI model service)
8. whatsapp_api (Express + Baileys)
9. MongoDB (session/auth state for Baileys)
10. WhatsApp Network (external)
b. Interactions & Dataflow:
- User → NGINX: incoming HTTP/HTTPS requests (serving static & dynamic content).
- NGINX → Django: proxies to Django’s WSGI/ASGI interface.
- Django → Postgres: ORM-based CRUD operations.
- Django (github_service) → GitHub API: OAuth token exchanges, issue fetch/creation.
- Django (whatsapp_messages) → whatsapp_app: POST/GET messages & webhooks.
- whatsapp_app → Ollama: AI completions, ACL requests.
- whatsapp_app → whatsapp_api: queueing outbound messages or handling inbound events.
- whatsapp_api ↔ WhatsApp: long-polling or WebSocket via Baileys; uses MongoDB for auth/session.
c. Architectural Patterns & Principles:
– Clear layer separation: Web/API (Django) vs. message-processing microservices.
– Modular design: each Django “app” addresses a bounded context (students, wallet, GitHub, etc.).
– Service-oriented approach for messaging and AI.
– Containerization & infrastructure as code (Docker Compose, GitHub Actions).

##### Final Checklist
[ ] Container boundaries drawn (NGINX, Django, Microservices, Databases).
[ ] Intra-container subcomponents identified (six Django apps).
[ ] Deployment artifacts indicated (Docker Compose, GitHub Actions CI/CD).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Intranet Infrastructure
    subgraph "User & Proxy Layer"
        direction TB
        Browser["Web Browser"]:::external
        CloudFlare["CloudFlare CDN"]:::infra
        NGINX["NGINX Reverse Proxy"]:::infra
    end

    %% Django Service
    subgraph "Django Intranet Service" 
        direction TB
        DjangoEntry["ASGI/WSGI Entrypoints"]:::backend
        subgraph "Django Apps"
            direction TB
            CoreApp["Core Module"]:::backend
            UsersApp["Users Module"]:::backend
            StudentApp["Student Module"]:::backend
            WalletApp["Wallet Module"]:::backend
            GitHubSvcApp["GitHub Service Module"]:::backend
            WhatsAppMsgApp["WhatsApp Messages Module"]:::backend
        end
        SharedTemplates["Shared Django Templates"]:::backend
    end

    %% Microservices Layer
    subgraph "Microservices"
        direction TB
        WhatsAppApp["whatsapp_app (FastAPI + Ollama)"]:::microservice
        WhatsAppAPI["whatsapp_api (Express + Baileys)"]:::microservice
        Ollama["Ollama AI Service"]:::microservice
    end

    %% Datastores
    subgraph "Datastores"
        direction TB
        PostgresDb["Postgres Database"]:::database
        MongoDB["MongoDB Session Store"]:::database
    end

    %% External Services
    subgraph "External APIs"
        direction TB
        GitHubAPI["GitHub REST API"]:::external
        WhatsAppNetwork["WhatsApp Network"]:::external
    end

    %% CI/CD & Infra Config
    subgraph "Infrastructure Config & CI/CD"
        direction TB
        DockerCompose["Docker Compose Configs"]:::infra
        CICDWorkflows["GitHub Actions Workflows"]:::infra
    end

    %% Connections
    Browser -->|"HTTP/HTTPS"| CloudFlare
    CloudFlare -->|"HTTP/HTTPS"| NGINX
    NGINX -->|"WSGI/ASGI"| DjangoEntry
    DjangoEntry -->|"ORM CRUD"| PostgresDb
    GitHubSvcApp -->|"OAuth & Issues"| GitHubAPI
    WhatsAppMsgApp -->|"REST/Webhook"| WhatsAppApp
    WhatsAppApp -->|"ACL & Completions"| Ollama
    WhatsAppApp -->|"Queue Messages"| WhatsAppAPI
    WhatsAppAPI -->|"WS/WebSocket"| WhatsAppNetwork
    WhatsAppAPI -->|"Auth Session"| MongoDB
    DockerCompose --> DjangoEntry
    DockerCompose --> WhatsAppApp
    DockerCompose --> WhatsAppAPI
    DockerCompose --> Ollama
    CICDWorkflows --> DockerCompose

    %% Click Events
    click NGINX "https://github.com/codaqui/tutor/blob/main/nginx/nginx.conf"
    click DjangoEntry "https://github.com/codaqui/tutor/blob/main/codaqui/asgi.py"
    click CoreApp "https://github.com/codaqui/tutor/tree/main/core/"
    click UsersApp "https://github.com/codaqui/tutor/tree/main/users/"
    click StudentApp "https://github.com/codaqui/tutor/tree/main/student/"
    click WalletApp "https://github.com/codaqui/tutor/tree/main/wallet/"
    click GitHubSvcApp "https://github.com/codaqui/tutor/tree/main/github_service/"
    click WhatsAppMsgApp "https://github.com/codaqui/tutor/tree/main/whatsapp_messages/"
    click SharedTemplates "https://github.com/codaqui/tutor/tree/main/templates/"
    click DockerCompose "https://github.com/codaqui/tutor/blob/main/docker-compose.yml"
    click CICDWorkflows "https://github.com/codaqui/tutor/blob/main/.github/workflows/build_and_deploy.yml"
    click WhatsAppAPI "https://github.com/codaqui/tutor/tree/main/whatsapp_api/"
    click WhatsAppApp "https://github.com/codaqui/tutor/blob/main/whatsapp_app/main.py"
    click Ollama "https://github.com/codaqui/tutor/tree/main/ollama/Dockerfile"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef infra fill:#bbf,stroke:#333,stroke-width:1px
    classDef backend fill:#bfb,stroke:#333,stroke-width:1px
    classDef microservice fill:#fbf,stroke:#333,stroke-width:1px
    classDef database fill:#ffb,stroke:#333,stroke-width:1px
```
