# haq-nawaz-malik/agentic_resume architecture

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

- Interactive diagram: https://gitdiagram.com/haq-nawaz-malik/agentic_resume
- Repository: https://github.com/haq-nawaz-malik/agentic_resume

## Overview

##### Project Type and Purpose
- AgenticResume is a full-stack web application that automates resume tailoring and interview prep by orchestrating multiple AI agents.
- Frontend: React + Tailwind CSS UI for user auth, resume/job management, and dashboard.
- Backend: Flask REST API with SQLAlchemy for data modeling and JWT for auth.
- AI Component: CrewAI-based multi-agent system (researcher, profiler, strategist, preparer).
- Database: PostgreSQL.
- External Services: OpenAI API for language tasks, Serper for web search.

##### File Structure Analysis
- Top Level:
– ai/ → AI agents & tasks & tooling (file scraping, web search).
– backend/ → Flask app, config, models, routes, services, utils.
– frontend/ → React SPA structure (components, pages, services, context).
– tests/ → pytest test suites for auth and resume flows.
– Dockerfile(s) & docker-compose.yml → container definitions for local/dev setup.
- Architectural Patterns:
– Layered backend (models → services → routes).
– Componentized frontend (layout, UI, forms, pages, context).
– Micro-service-style isolation between AI logic (ai/) and core API (backend/).

##### Key README Insights
- Four specialized AI agents collaborating via CrewAI.
- Explicit callouts of tech stack and deployment with Docker Compose.

a. Main Containers:
1. Frontend (React SPA + Nginx)
2. Backend API (Flask + SQLAlchemy + JWT)
3. AI Agents Module (CrewAI orchestration)
4. Database (PostgreSQL)
5. External Services (OpenAI, Serper)
b. Relationships and Data Flows:
– User ↔ Frontend: HTTP/HTTPS (login, dashboard, resume builder)
– Frontend → Backend API: REST calls via api.js service layer
– Backend → Database: SQL over TCP (via SQLAlchemy)
– Backend → AI Module: gRPC/HTTP or Python import calls to ai_service.py
– AI Module → OpenAI API & Serper API: HTTPS requests for LLM and web search
– Backend → Frontend: REST JSON responses
– User → Export: PDF/Markdown generation handled by backend or AI module
c. Architectural Patterns & Principles:
– Separation of concerns: UI, business logic, data, and AI logic are decoupled.
– Layered modularity in backend (routes → services → models).
– Component and context pattern in frontend for state management.
– Dependency inversion: ai_service abstracts AI interactions behind a service interface.
d. Key Technologies & Frameworks:
– Frontend: React, Tailwind CSS, Context API, Jest for tests
– Backend: Flask, Flask-JWT-Extended, SQLAlchemy, pytest
– AI Module: CrewAI framework, OpenAI Python client
– DevOps: Docker, Docker Compose, Nginx

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Container
    subgraph "Frontend Container (React SPA + Nginx)" 
        direction TB
        FE_NGINX["Nginx"]:::frontend
        FE_APP["React App"]:::frontend
        FE_API_SVC["api.js Service"]:::frontend
        FE_AUTH_CTX["AuthContext"]:::frontend
        FE_COMPONENTS["Components"]:::frontend
        FE_PAGES["Pages"]:::frontend
        FE_APP -->|uses| FE_API_SVC
        FE_APP -->|uses| FE_AUTH_CTX
        FE_APP -->|renders| FE_COMPONENTS
        FE_APP -->|navigates| FE_PAGES
        FE_NGINX -->|serves| FE_APP
    end

    %% Backend Container
    subgraph "Backend API (Flask + SQLAlchemy + JWT)" 
        direction TB
        BE_APP["app.py"]:::backend
        BE_AUTH_ROUTE["Auth Routes"]:::backend
        BE_RES_ROUTE["Resume Routes"]:::backend
        BE_JOB_ROUTE["JobApp Routes"]:::backend
        BE_AUTH_SVC["AuthService"]:::backend
        BE_AI_SVC["AIService"]:::backend
        BE_MODELS["Models"]:::backend
        BE_UTILS["Utils"]:::backend
        BE_APP -->|includes| BE_AUTH_ROUTE
        BE_APP -->|includes| BE_RES_ROUTE
        BE_APP -->|includes| BE_JOB_ROUTE
        BE_AUTH_ROUTE -->|calls| BE_AUTH_SVC
        BE_RES_ROUTE -->|calls| BE_AI_SVC
        BE_JOB_ROUTE -->|calls| BE_AI_SVC
        BE_AUTH_SVC -->|validates| BE_UTILS
        BE_AI_SVC -->|imports| BE_MODELS
        BE_AI_SVC -->|calls| AI_MODULE
        BE_MODELS -->|defines| BE_UTILS
    end

    %% AI Module Container
    subgraph "AI Agents Module (CrewAI)" 
        direction TB
        AI_CREW["crew.py"]:::ai
        AI_RESEARCH["Researcher Agent"]:::ai
        AI_PROFILER["Profiler Agent"]:::ai
        AI_STRATEGIST["Strategist Agent"]:::ai
        AI_PREPARER["Preparer Agent"]:::ai
        AI_TASKS["Task Modules"]:::ai
        AI_TOOLS["Tools"]:::ai
        AI_CREW -->|orchestrates| AI_RESEARCH
        AI_CREW -->|orchestrates| AI_PROFILER
        AI_CREW -->|orchestrates| AI_STRATEGIST
        AI_CREW -->|orchestrates| AI_PREPARER
        AI_RESEARCH -->|executes| AI_TASKS
        AI_PROFILER -->|executes| AI_TASKS
        AI_STRATEGIST -->|executes| AI_TASKS
        AI_PREPARER -->|executes| AI_TASKS
        AI_TASKS -->|use| AI_TOOLS
    end

    %% Database Container
    subgraph "Database (PostgreSQL)" 
        direction TB
        DB["PostgreSQL"]:::db
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        EXT_OPENAI["OpenAI API"]:::external
        EXT_SERPER["Serper API"]:::external
    end

    %% Users and Data Flow
    User["User"]:::external
    User -->|HTTP/HTTPS| FE_NGINX
    FE_APP -->|REST| BE_APP
    BE_APP -->|SQL| DB
    BE_APP -->|calls| AI_MODULE
    AI_MODULE -->|HTTPS| EXT_OPENAI
    AI_MODULE -->|HTTPS| EXT_SERPER
    BE_APP -->|JSON| FE_APP

    %% Click Events - Frontend
    click FE_NGINX "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/frontend/nginx.conf"
    click FE_NGINX "https://github.com/haq-nawaz-malik/agentic_resume/tree/master/frontend/Dockerfile"
    click FE_APP "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/frontend/src/App.js"
    click FE_API_SVC "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/frontend/src/services/api.js"
    click FE_COMPONENTS "https://github.com/haq-nawaz-malik/agentic_resume/tree/master/frontend/src/components"
    click FE_PAGES "https://github.com/haq-nawaz-malik/agentic_resume/tree/master/frontend/src/pages"
    click FE_AUTH_CTX "https://github.com/haq-nawaz-malik/agentic_resume/tree/master/frontend/src/context"
    click FE_INDEX "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/frontend/public/index.html"

    %% Click Events - Backend
    click BE_APP "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/backend/app.py"
    click BE_AUTH_ROUTE "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/backend/routes/auth.py"
    click BE_RES_ROUTE "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/backend/routes/resumes.py"
    click BE_JOB_ROUTE "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/backend/routes/job_applications.py"
    click BE_AUTH_SVC "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/backend/services/auth_service.py"
    click BE_AI_SVC "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/backend/services/ai_service.py"
    click BE_UTILS "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/backend/utils/validators.py"
    click BE_UTILS "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/backend/utils/errors.py"
    click BE_MODELS "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/backend/models/__init__.py"
    click BE_MODELS "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/backend/models/user.py"
    click BE_MODELS "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/backend/models/resume.py"
    click BE_MODELS "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/backend/models/job_application.py"
    click BE_CONFIG "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/backend/config.py"

    %% Click Events - AI Module
    click AI_CREW "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/ai/crew.py"
    click AI_RESEARCH "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/ai/agents/researcher.py"
    click AI_PROFILER "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/ai/agents/profiler.py"
    click AI_STRATEGIST "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/ai/agents/resume_strategist.py"
    click AI_PREPARER "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/ai/agents/interview_preparer.py"
    click AI_TASKS "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/ai/tasks/research_task.py"
    click AI_TASKS "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/ai/tasks/profile_task.py"
    click AI_TASKS "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/ai/tasks/resume_task.py"
    click AI_TASKS "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/ai/tasks/interview_task.py"
    click AI_TOOLS "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/ai/tools/search_tools.py"
    click AI_TOOLS "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/ai/tools/file_tools.py"
    click AI_TOOLS "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/ai/tools/scrape_tools.py"

    %% Click Events - Database & External
    click DB "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/docker-compose.yml"
    click BE_CONFIG "https://github.com/haq-nawaz-malik/agentic_resume/blob/master/backend/config.py"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#E6FFDA,stroke:#22863A,stroke-width:1px
    classDef ai fill:#FFE4B5,stroke:#D2691E,stroke-width:1px
    classDef db fill:#F0F0F0,stroke:#6A737D,stroke-width:1px
    classDef external fill:#EEE5FF,stroke:#6F42C1,stroke-width:1px
```
