# c4-job-cheat/server architecture

> Architecture diagram of the GitHub repository c4-job-cheat/server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/c4-job-cheat/server
- Repository: https://github.com/c4-job-cheat/server

## Overview

##### Project type and purpose
- This is a Django-based monolithic backend API service (“job_cheat”) composed of multiple Django apps (api, core, cover_letters, interviews, job_search, personas).
- Purpose: expose REST endpoints for job-search workflows—persona generation, cover-letter drafting, interview prep, competency evaluation, and health checks—while orchestrating calls to AI services (ChatGPT, Cohere, Whisper, Gemini), a vector store (Pinecone), and Firebase (Auth, Firestore, Storage).

##### File structure
- Top-level: manage.py, ASGI/WSGI entrypoints, `job_cheat/job_cheat` (settings, URLs).
- Apps:
- api: high-level entrypoints and URL routing
- core: shared models, serializers, data, and “services” layer invoking AI or storage backends
- cover_letters, interviews, job_search, personas: domain-specific views, serializers, services
- docs/: API specifications, database schema, feature/architecture notes.
- Configuration: pyproject.toml, requirements.txt, .python-version, .gitignore.
- Testing: each service under core/services/tests and per-app test modules.

##### Architecture insights (from docs/miscl/ARCHITECTURE.md & database-schema.md)
- Single Django process served via ASGI (uvicorn/daphne) or WSGI (gunicorn).
- PostgreSQL (or similar relational DB) for core models.
- Firebase Firestore for persona/user data sync and Storage for file assets.
- Pinecone for similarity search embeddings.
- External AI endpoints: OpenAI, Cohere, Google Gemini, Whisper.

##### Summary
- Layer in domain apps and async processes (RAG embedding jobs).
- Django app and service is represented.
- With technology names and endpoints per docs/api-doc.
- Validate against docs/miscl/ARCHITECTURE.md and database-schema.md to capture data relationships.

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Client
    Client["Client (Web/Mobile)"]:::external
    %% Load Balancer/API Gateway
    LB["Load Balancer / API Gateway"]:::gateway

    %% Django API Server
    subgraph "Django API Server" 
        direction TB
        ASGI["ASGI Entrypoint"]:::entrypoint
        WSGI["WSGI Entrypoint"]:::entrypoint
        Settings["Settings"]:::config
        URLs["URL Config"]:::config
        Manage["manage.py"]:::script

        subgraph "API Layer (Django Apps)"
            direction TB
            API_app["api app"]:::app
            Personas_app["personas app"]:::app
            CoverLetters_app["cover_letters app"]:::app
            Interviews_app["interviews app"]:::app
            JobSearch_app["job_search app"]:::app
        end

        subgraph "Core Shared"
            direction TB
            Auth["Authentication"]:::core
            DataFixtures["Data Fixtures"]:::core
            SerializersCore["Serializers"]:::core
            Utils["Utilities"]:::core
        end

        subgraph "Core Services (External Integrations)"
            direction TB
            ChatGPT["ChatGPT Converter"]:::service
            Cohere["Cohere Service"]:::service
            Gemini["Gemini Service"]:::service
            Whisper["Whisper Service"]:::service
            PineconeStore["Pinecone Service"]:::service
            RAGVector["RAG Vector Store"]:::service
            RagEmbedJob["RAG Embedding Job"]:::service
            ConvRagEmbed["Conversation RAG Embedding Job"]:::service
            RagEmbedService["RAG Embedding Service"]:::service
            ConvRagService["Conversation RAG Service"]:::service
            CompetencyEval["RAG Competency Evaluator"]:::service
            FirebasePersonas["Firebase Personas"]:::service
            FirebaseUsers["Firebase Users"]:::service
            FirebaseStorage["Firebase Storage"]:::service
        end
    end

    %% Data Stores & External Services
    subgraph "Data Stores & External"
        direction TB
        Postgres["PostgreSQL"]:::database
        FirebaseAuth["Firebase Auth"]:::database
        Firestore["Firestore"]:::database
        Storage["Storage"]:::database
        Pinecone["Pinecone Vector Store"]:::storage
        subgraph "External AI Services"
            direction TB
            OpenAI["OpenAI GPT"]:::external
            CohereExt["Cohere"]:::external
            GeminiExt["Google Gemini"]:::external
            WhisperExt["Whisper"]:::external
        end
    end

    %% Monitoring & Health
    Health["Health Check Endpoints"]:::monitor

    %% Connections
    Client -->|"HTTP/REST"| LB
    LB -->|"HTTP/REST"| ASGI
    LB -->|"HTTP/REST"| WSGI
    ASGI --> Settings
    WSGI --> Settings
    Settings --> URLs
    URLs --> API_app
    URLs --> Personas_app
    URLs --> CoverLetters_app
    URLs --> Interviews_app
    URLs --> JobSearch_app

    API_app -->|calls Views/Serializers| CoreServices
    Personas_app -->|calls Services| CoreServices
    CoverLetters_app -->|calls Services| CoreServices
    Interviews_app -->|calls Services| CoreServices
    JobSearch_app -->|calls Services| CoreServices

    CoreServices((Core Services)) -.-> Auth
    CoreServices -.-> DataFixtures
    CoreServices -.-> SerializersCore
    CoreServices -.-> Utils

    CoreServices -->|ORM| Postgres
    CoreServices -->|SDK| FirebaseAuth
    CoreServices -->|SDK| Firestore
    CoreServices -->|SDK| Storage
    CoreServices -->|SDK| Pinecone
    ChatGPT -->|HTTP API| OpenAI
    Cohere -->|HTTP API| CohereExt
    Gemini -->|HTTP API| GeminiExt
    Whisper -->|HTTP API| WhisperExt

    Health -->|probe| Postgres
    Health -->|probe| FirebaseAuth
    Health -->|probe| Firestore
    Health -->|probe| Pinecone

    %% Click Events
    click ASGI "https://github.com/c4-job-cheat/server/blob/main/job_cheat/job_cheat/asgi.py"
    click WSGI "https://github.com/c4-job-cheat/server/blob/main/job_cheat/job_cheat/wsgi.py"
    click Settings "https://github.com/c4-job-cheat/server/blob/main/job_cheat/job_cheat/settings.py"
    click URLs "https://github.com/c4-job-cheat/server/blob/main/job_cheat/job_cheat/urls.py"
    click Manage "https://github.com/c4-job-cheat/server/blob/main/job_cheat/manage.py"
    click API_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/api/urls.py"
    click API_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/api/views.py"
    click API_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/api/serializers.py"
    click API_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/api/models.py"
    click Personas_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/personas/api/serializers.py"
    click Personas_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/personas/views.py"
    click Personas_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/personas/urls.py"
    click CoverLetters_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/cover_letters/views.py"
    click CoverLetters_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/cover_letters/urls.py"
    click CoverLetters_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/cover_letters/serializers.py"
    click CoverLetters_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/cover_letters/services/cover_letter_service.py"
    click Interviews_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/interviews/views.py"
    click Interviews_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/interviews/urls.py"
    click Interviews_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/interviews/serializers.py"
    click Interviews_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/interviews/services/interview_service.py"
    click JobSearch_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/job_search/views.py"
    click JobSearch_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/job_search/urls.py"
    click JobSearch_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/job_search/serializers.py"
    click JobSearch_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/job_search/services/job_matching.py"
    click JobSearch_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/job_search/services/job_posting.py"
    click JobSearch_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/job_search/services/recommendation.py"
    click JobSearch_app "https://github.com/c4-job-cheat/server/blob/main/job_cheat/job_search/services/scrap_service.py"
    click Auth "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/authentication.py"
    click DataFixtures "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/data/job-data.json"
    click SerializersCore "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/serializers.py"
    click Utils "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/utils.py"
    click ChatGPT "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/services/chatgpt_converter.py"
    click Cohere "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/services/cohere_service.py"
    click Gemini "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/services/gemini_service.py"
    click Whisper "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/services/whisper_service.py"
    click PineconeStore "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/services/pinecone_service.py"
    click RAGVector "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/services/rag_vector_store.py"
    click RagEmbedJob "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/services/rag_embedding_job.py"
    click ConvRagEmbed "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/services/conversation_rag_embedding_job.py"
    click RagEmbedService "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/services/rag_embedding_service.py"
    click ConvRagService "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/services/conversation_rag_service.py"
    click CompetencyEval "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/services/rag_competency_evaluator.py"
    click FirebasePersonas "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/services/firebase_personas.py"
    click FirebaseUsers "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/services/firebase_users.py"
    click FirebaseStorage "https://github.com/c4-job-cheat/server/blob/main/job_cheat/core/services/firebase_storage.py"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef gateway fill:#bbf,stroke:#333,stroke-width:1px
    classDef entrypoint fill:#cff,stroke:#333,stroke-width:1px
    classDef config fill:#eef,stroke:#333,stroke-width:1px
    classDef script fill:#dfd,stroke:#333,stroke-width:1px
    classDef app fill:#bbf,stroke:#333,stroke-width:1px
    classDef core fill:#ddf,stroke:#333,stroke-width:1px
    classDef service fill:#bfc,stroke:#333,stroke-width:1px
    classDef database fill:#afa,stroke:#333,stroke-width:1px
    classDef storage fill:#fea,stroke:#333,stroke-width:1px
    classDef monitor fill:#ffd,stroke:#333,stroke-width:1px
```
