# k8pil/ttt25-private architecture

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

- Interactive diagram: https://gitdiagram.com/k8pil/ttt25-private
- Repository: https://github.com/k8pil/ttt25-private

## Overview

##### Project Type & Purpose
- Career Conquer is a monolithic full-stack Flask web application for career guidance and interactive interview practice.
- It combines REST APIs and server-rendered pages (MVC pattern), machine-learning body-language analysis, OCR resume parsing, and recommendation engines.

##### Main Architectural Components
a. Client Browser (Frontend)
- UI: HTML templates (templates/*.html)
- Static assets: CSS/JS (static/, app/static/)
- Webcam & JS modules (guidance.js, interview-chat.js) for real-time video capture.
b. Web Server (Flask Application)
- Entry point: app.py / run.py
- Blueprints / Routes:
- main_routes (login/signup/dashboard)
- api_routes (JSON endpoints for AJAX/video data)
- interview_routes (mock interview flows)
- Service layer (app/services & interview_advisor package):
- resume_service: invokes PyMuPDF, Tesseract OCR, file storage
- interview_service: orchestrates video analysis, emotion scoring via MediaPipe
- tts_service: text-to-speech responses
- recommendation engine (improved_career_recommendations.py, interview_advisor/recommendation.py)
- Data models & persistence (app/models/database.py & SQLAlchemy)
c. Data Stores
- SQLite (interview_metrics.db, data/*.sqlite) with SQLAlchemy ORM
- JSON metric files (data/interview_metrics_*.json) for offline analysis
d. External Libraries & Tools
- MediaPipe (body-language detection)
- scikit-learn (career matching classifier)
- PyMuPDF & Tesseract OCR (resume parsing)
- Flask extensions (flask-login, etc.)
e. Supporting Scripts
- manage_eye_db.py / create_eye_database.py: DB migration/scripts
- check_db_tables.py: health checks
- video_analysis.py / audio_to_text.py: standalone processing modules
- run_interview_advisor.py: wrapper to start advisor engine

##### Component Interactions & Data Flow
- User browser → HTTP(S) → Flask (routes)
- Routes call Services → External libraries (OCR, MediaPipe, ML models) → process data
- Services persist results → Database (SQLAlchemy) + JSON files
- Flask returns rendered templates or JSON payloads → Browser UI updates
- Real-time video frames streamed via WebRTC/JS → Flask API → MediaPipe → feedback via WebSocket/AJAX

##### Architectural Patterns / Design Principles
- MVC / Blueprint separation: clear split between routes (controllers), services (business logic), models (data layer), templates/static (view layer).
- Service Layer: isolates ML/OCR integrations from controllers.
- Modular Python packages (interview_advisor) for reusable components.
- Single-process monolith, no microservices—simplifies deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Browser" 
        direction TB
        Templates["HTML Templates"]:::client
        StaticAssets["Static Assets & JS Modules"]:::client
    end

    Templates -->|renders| Flask["Flask HTTP API & Server-Rendered Pages"]:::server
    StaticAssets -->|loads| Flask

    %% Server Layer
    subgraph "Flask Application" 
        direction TB
        Entry["Entry Point\n(app.py / run.py)"]:::server
        subgraph "Routes (Controllers)"
            direction TB
            MainRoutes["main_routes"]:::server
            APIRoutes["api_routes"]:::server
            InterviewRoutes["interview_routes"]:::server
        end
        subgraph "Services (Business Logic)"
            direction TB
            ResumeSvc["Resume Service"]:::server
            InterviewSvc["Interview Service"]:::server
            TTSSvc["TTS Service"]:::server
            RecEngine["Recommendation Engine"]:::server
        end
        Models["Models & ORM"]:::server
    end

    Flask --> Entry
    Entry --> MainRoutes
    Entry --> APIRoutes
    Entry --> InterviewRoutes
    MainRoutes --> ResumeSvc
    APIRoutes -->|JSON/AJAX| ResumeSvc
    InterviewRoutes --> InterviewSvc
    ResumeSvc --> Models
    InterviewSvc --> Models
    TTSSvc --> MainRoutes
    RecEngine --> Models

    %% External Libraries & ML Models
    subgraph "External Tools" 
        direction TB
        OCR["Tesseract OCR & PyMuPDF"]:::external
        MediaPipe["MediaPipe Emotion Detector"]:::external
        SKLearn["scikit-learn Classifier"]:::external
        TFModel["ML Model (model.h5)"]:::external
    end

    ResumeSvc -->|parse resume| OCR
    InterviewSvc -->|analyze video| MediaPipe
    RecEngine -->|classify career| SKLearn
    RecEngine -->|load model| TFModel

    %% Data Layer
    subgraph "Data Stores"
        direction TB
        SQLite["SQLite DB\n(interview_metrics.db)"]:::data
        JSONStore["JSON Metric Files"]:::data
    end

    ServicesSubgraph[Services] --> SQLite
    ServicesSubgraph --> JSONStore
    ResumeSvc --> SQLite
    InterviewSvc --> JSONStore

    %% Supporting Scripts
    subgraph "Supporting Scripts"
        direction TB
        DBMigration["DB Migration Scripts"]:::server
        HealthCheck["Health Checks"]:::server
        OfflineProc["Offline Processing Modules"]:::server
    end

    DBMigration --> SQLite
    HealthCheck --> Models
    OfflineProc --> JSONStore

    %% Click Events
    click Templates "https://github.com/k8pil/ttt25-private/tree/main/app/templates/"
    click StaticAssets "https://github.com/k8pil/ttt25-private/blob/main/app/static/css/style.css"
    click StaticAssets "https://github.com/k8pil/ttt25-private/tree/main/static/assets/"
    click StaticAssets "https://github.com/k8pil/ttt25-private/blob/main/static/guidance.js"
    click StaticAssets "https://github.com/k8pil/ttt25-private/blob/main/static/interview-chat.js"
    click StaticAssets "https://github.com/k8pil/ttt25-private/blob/main/static/modern.css"
    click StaticAssets "https://github.com/k8pil/ttt25-private/blob/main/static/navbar.css"
    click StaticAssets "https://github.com/k8pil/ttt25-private/blob/main/static/style.css"
    click StaticAssets "https://github.com/k8pil/ttt25-private/blob/main/static/styles.css"
    click StaticAssets "https://github.com/k8pil/ttt25-private/blob/main/static/theme.js"
    click Entry "https://github.com/k8pil/ttt25-private/blob/main/app.py"
    click Entry "https://github.com/k8pil/ttt25-private/blob/main/run.py"
    click MainRoutes "https://github.com/k8pil/ttt25-private/blob/main/app/routes/main_routes.py"
    click APIRoutes "https://github.com/k8pil/ttt25-private/blob/main/app/routes/api_routes.py"
    click InterviewRoutes "https://github.com/k8pil/ttt25-private/blob/main/app/routes/interview_routes.py"
    click ResumeSvc "https://github.com/k8pil/ttt25-private/blob/main/app/services/resume_service.py"
    click ResumeSvc "https://github.com/k8pil/ttt25-private/blob/main/interview_advisor/resume_processor.py"
    click InterviewSvc "https://github.com/k8pil/ttt25-private/blob/main/app/services/interview_service.py"
    click InterviewSvc "https://github.com/k8pil/ttt25-private/blob/main/interview_advisor/interview.py"
    click TTSSvc "https://github.com/k8pil/ttt25-private/blob/main/app/services/tts_service.py"
    click TTSSvc "https://github.com/k8pil/ttt25-private/blob/main/interview_advisor/tts_service.py"
    click RecEngine "https://github.com/k8pil/ttt25-private/blob/main/improved_career_recommendations.py"
    click RecEngine "https://github.com/k8pil/ttt25-private/blob/main/interview_advisor/recommendation.py"
    click Models "https://github.com/k8pil/ttt25-private/blob/main/app/models/database.py"
    click Models "https://github.com/k8pil/ttt25-private/blob/main/models.py"
    click SQLite "https://github.com/k8pil/ttt25-private/blob/main/interview_metrics.db"
    click SQLite "https://github.com/k8pil/ttt25-private/blob/main/data/interview_metrics.sqlite"
    click JSONStore "https://github.com/k8pil/ttt25-private/blob/main/data/*.json"
    click TFModel "https://github.com/k8pil/ttt25-private/blob/main/model.h5"
    click DBMigration "https://github.com/k8pil/ttt25-private/blob/main/manage_eye_db.py"
    click DBMigration "https://github.com/k8pil/ttt25-private/blob/main/create_eye_database.py"
    click HealthCheck "https://github.com/k8pil/ttt25-private/blob/main/check_db_tables.py"
    click OfflineProc "https://github.com/k8pil/ttt25-private/blob/main/audio_to_text.py"
    click OfflineProc "https://github.com/k8pil/ttt25-private/blob/main/video_analysis.py"
    click OfflineProc "https://github.com/k8pil/ttt25-private/blob/main/run_interview_advisor.py"

    %% Styles
    classDef client fill:#a8d1ff,stroke:#000
    classDef server fill:#b8e5a0,stroke:#000
    classDef data fill:#ffe299,stroke:#000
    classDef external fill:#cccccc,stroke:#000
```
