# praneeth-18/talenttrek-ai-powered-career-companion architecture

> Architecture diagram of the GitHub repository praneeth-18/talenttrek-ai-powered-career-companion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/praneeth-18/talenttrek-ai-powered-career-companion
- Repository: https://github.com/praneeth-18/talenttrek-ai-powered-career-companion

## Overview

##### Project Type and Purpose
- This is a full-stack, microservices-oriented job portal platform. It combines:
- A Next.js 15 front-end (React + Tailwind) with built-in API routes.
- Two Python-based backends:
– `resume-service` (FastAPI) for AI-driven resume customization.
– `AI_Interviewer` (Flask/FastAPI) for mock interviews with transcription, TTS, and feedback.
- Scheduled Python scripts for job scraping and link processing.
- PostgreSQL (AWS RDS) for main data and MySQL for interview session data.
- External services: AWS Cognito for auth, OpenAI API for AI tasks, S3 (optionally) for file storage.

##### File Structure
- Top-level directories:
- `src/` – Next.js application (UI + serverless API routes).
- `resume-service/` – Microservice with `frontend/` and `backend/`.
- `AI_Interviewer/` – Interview microservice.
- `scripts/` – Standalone Python/JS job-scraping tools.
- `prisma/` – Prisma ORM schema & migrations for Postgres.
- Configuration files: `.env.local`, Dockerfiles, `docker-compose.yml`, `run_*.sh` scripts.
- Each Python service has its own `requirements.txt` and entrypoint (Uvicorn/Docker).

##### Main Components and Interactions
a. Frontend (Next.js):
- UI pages, React components, AuthContext.
- Makes HTTP calls to:
- Next.js API routes for user actions, applications, resume downloads.
- Resume Service at `RESUME_SERVICE_URL` for PDF customization.
- Interview Service at `http://localhost:5000` (or Docker port) for chat & sessions.
- Uses AWS Cognito for user login/registration flows via JS SDK.
b. Next.js API Layer (Serverless Functions):
- Routes under `src/app/api/…` handling CRUD for applications, resumes, user data.
- Uses Prisma client to read/write PostgreSQL on AWS RDS.
- Proxies or redirects to external microservices for specialized tasks.
c. Resume Service (FastAPI):
- Receives `/api/customize` requests, calls LLM (OpenAI) to generate Markdown or LaTeX.
- Converts to PDF via `json_to_pdf.py` and `generate_pdf.py`.
- Optionally stores/retrieves templates from S3 via `s3_utils.py`.
d. AI Interviewer Service (Flask/FastAPI):
- Manages `/interviews`, `/api/chat`, transcription, question generation, evaluation.
- Stores sessions and transcripts in MySQL (connected via `database.py`).
- Calls OpenAI for question generation and evaluation.
e. Job-Scraper Scripts:
- Scheduled via `run_job_scheduler.sh` / `job_scheduler.py`.
- Scrape listings, normalize data, insert into AWS RDS Postgres (`db-connector.ts` or direct SQL).
- Fetch actual links with `fetch_actual_links.sh`.
f. Databases:
- PostgreSQL (AWS RDS): job listings, user applications, interactions.
- MySQL: interview session data and transcripts.

##### Architectural Patterns and Design Principles
- Microservices: resume customization & interview services are isolated deployments.
- Serverless functions for the main API, reducing infrastructure overhead.
- Shared database for core data, per-service storage for specialized data.
- Asynchronous scheduled tasks for data ingestion (job scraping).
- Externalization of auth (AWS Cognito) and AI compute (OpenAI).

##### Essential Elements
- Labels: Component names + key tech (e.g., “Next.js App (React + Tailwind)”).
- Blue: User-facing UI
- Green: Core API
- Orange/Purple: Microservices
- Yellow: Databases
- Grey: External
- Notes:
- Authentication flow via Cognito.
- AI calls to OpenAI.
- Scheduled scraping tasks.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        User["User"]:::external
        NextApp["Next.js App<br/>(React + Tailwind)"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        API["Next.js API Layer"]:::api
        AuthCtx["AuthContext"]:::frontend
        AwsConfig["AWS Config"]:::frontend
        UserSvc["User Service"]:::api
    end

    %% Microservices
    subgraph "Resume Service" 
        direction TB
        RS_FE["Resume Service FE"]:::micro1
        RS_BE["Resume Service BE"]:::micro1
        PDFGen["PDF Generator"]:::micro1
        Prompts["Prompt Definitions"]:::micro1
        S3Utils["S3 Utilities"]:::micro1
    end

    subgraph "Interview Service"
        direction TB
        IS_App["Interview Service Entry"]:::micro2
        IS_API["Interview API Layer"]:::micro2
        DBConn["DB Connection"]:::micro2
        Models["Data Models"]:::micro2
        OAI["OpenAI Integration"]:::micro2
    end

    %% Batch Jobs
    subgraph "Batch Jobs"
        direction TB
        SchedulerRoot["run_job_scheduler.sh"]:::batch
        SchedulerScr["scripts/job_scheduler.py"]:::batch
        ListingProc["scripts/job_listing_processor.py"]:::batch
        NewListings["scripts/process_new_listings.py"]:::batch
        LinkFetchShell["fetch_actual_links.sh"]:::batch
        LinkFetchJS["scripts/fetch_actual_links.js"]:::batch
        CSVDL["scripts/csvdownload.py"]:::batch
        ImportCSV["scripts/import_csv_data.ts"]:::batch
    end

    %% Data Layer
    subgraph "Data Stores"
        direction TB
        Postgres["PostgreSQL (AWS RDS)"]:::database
        MySQL["MySQL (Interview Data)"]:::database
        S3["S3 Bucket"]:::external
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Cognito["AWS Cognito"]:::external
        OpenAI["OpenAI API"]:::external
    end

    %% Connections
    User --> NextApp
    NextApp -->|Uses Auth SDK| Cognito
    NextApp -->|REST POST /api/*| API
    NextApp -->|Calls Resume API Client| RSClient["Resume API Client"]:::api
    RSClient -->|HTTP /api/customize| RS_BE
    NextApp -->|REST /interview| IS_App

    API -->|Prisma ORM| Postgres
    API -->|Uses UserService| UserSvc
    API -->|Uses AuthContext| AuthCtx
    API -->|Uses AWS Config| AwsConfig

    RS_BE -->|Calls OpenAI| OpenAI
    RS_BE -->|Generates PDF| PDFGen
    PDFGen -->|Uploads/Downloads| S3
    RS_BE -->|Uses Prompts| Prompts
    PDFGen -->|Uses S3 Utils| S3Utils

    IS_App -->|Routes to API Layer| IS_API
    IS_API -->|Reads/Writes| MySQL
    IS_API -->|Calls OpenAI| OpenAI
    IS_API -->|Uses DB Conn| DBConn
    IS_API -->|Uses Models| Models
    IS_API -->|Uses OpenAI Service| OAI

    SchedulerRoot -.->|Cron| SchedulerScr
    SchedulerScr -.->|Scrapes| ListingProc
    ListingProc -.->|Processes| NewListings
    NewListings -.->|Inserts| Postgres
    ListingProc -.->|Fetch Links| LinkFetchShell
    LinkFetchShell -.->|JS Fetch| LinkFetchJS
    ListingProc -.->|CSV Download| CSVDL
    CSVDL -.->|Import| ImportCSV
    ImportCSV -.->|Data Load| Postgres

    %% Click Events
    click NextApp "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/tree/main/src/"
    click API "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/tree/main/src/app/api/"
    click AuthCtx "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/src/contexts/AuthContext.tsx"
    click AwsConfig "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/src/lib/aws-config.ts"
    click UserSvc "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/src/services/userService.ts"
    click RS_FE "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/tree/main/resume-service/frontend/"
    click RS_BE "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/resume-service/backend/main.py"
    click PDFGen "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/tree/main/resume-service/backend/pdf_generator/"
    click Prompts "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/resume-service/backend/prompts.py"
    click S3Utils "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/resume-service/backend/pdf_generator/s3_utils.py"
    click IS_App "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/AI_Interviewer/app.py"
    click IS_API "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/tree/main/AI_Interviewer/api/"
    click DBConn "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/AI_Interviewer/api/database.py"
    click Models "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/AI_Interviewer/api/models.py"
    click OAI "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/AI_Interviewer/api/openai_service.py"
    click SchedulerRoot "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/run_job_scheduler.sh"
    click SchedulerScr "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/scripts/job_scheduler.py"
    click ListingProc "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/scripts/job_listing_processor.py"
    click NewListings "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/scripts/process_new_listings.py"
    click LinkFetchShell "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/fetch_actual_links.sh"
    click LinkFetchJS "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/scripts/fetch_actual_links.js"
    click CSVDL "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/scripts/csvdownload.py"
    click ImportCSV "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/scripts/import_csv_data.ts"
    click RSClient "https://github.com/praneeth-18/talenttrek-ai-powered-career-companion/blob/main/src/lib/resume-service.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#005A9C,color:#005A9C
    classDef api fill:#DFFFE0,stroke:#4B8F29,color:#4B8F29
    classDef micro1 fill:#FFE5B4,stroke:#C45A00,color:#C45A00
    classDef micro2 fill:#E8D0FF,stroke:#6A00C4,color:#6A00C4
    classDef database fill:#FFF4C1,stroke:#B58F00,color:#B58F00
    classDef external fill:#E0E0E0,stroke:#666666,color:#333333
    classDef batch fill:#E0FFE0,stroke:#3D7E3D,color:#3D7E3D
```
