# rafacalassara/jobapplicationflow architecture

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

- Interactive diagram: https://gitdiagram.com/rafacalassara/jobapplicationflow
- Repository: https://github.com/rafacalassara/jobapplicationflow

## Overview

##### Project Type and Purpose
- This is an AI-driven, orchestrated pipeline service with a minimal frontend served by Gradio.
- Purpose: Given a user’s LinkedIn PDF resume, a job posting URL, and optional inputs, the system runs three “crews” of AI agents (resume tailoring, company research, email writing) to generate/output:
- A tailored resume (MD + PDF)
- A company research report
- A job-application email draft

##### High-Level File-Structure Analysis
- Top-level files & folders:
- app.py, main.py → entrypoints (Gradio UI & orchestration)
- .env.example, requirements.txt → configuration/dependencies
- Dockerfile, docker-compose.yml → containerization/deployment
- inputs/ → raw input templates (e.g., base_resume.md)
- crews/ → 3 sub-modules (tailor_resume_crew, companies_research_crew, email_writer_crew), each with:
– `<crew>.py` (crew implementation)
– config/agents.yaml, config/tasks.yaml (YAML-driven agent definitions)
- tools/ → helper scripts (PDF conversion, HTML styling, custom tools)

##### Extract Key Components
a. Frontend/UI
- Gradio interface defined in app.py
- Hosts web server at http://127.0.0.1:7860
b. Orchestrator Layer
- main.py (or embedded in app.py) that wires together UI inputs, crew invocations, and outputs
c. Crew Modules (Pipeline Stages)
- Tailor Resume Crew
- Companies Research Crew
- Email Writer Crew
Each crew reads its config, invokes AI agents via crewAI, and returns structured outputs.
d. Tools Library
- convert_resume_to_pdf.py
- convert_to_styled_html.py
- custom_tool.py
Used by crews to post-process raw AI outputs.
e. External Services
- OpenAI API (via crewAI)
- Serper API (for web/company scraping)
f. Data Stores / File System
- inputs/ for source files
- outputs/ (implicitly created at runtime) for final artifacts
g. Deployment
- Dockerfile (build image)
- docker-compose.yml (service orchestration)

##### Relationships & Data Flows
- User → Gradio UI (app.py)
- UI passes inputs → Orchestrator (main.py)
- Orchestrator sequentially triggers:
1. Tailor Resume Crew → uses LinkedIn PDF + job URL → outputs tailored MD resume
2. Companies Research Crew → uses job/company info → outputs company report
3. Email Writer Crew → uses resume + report → outputs draft email
- Each Crew may call:
- Tools library for transformations
- External APIs (OpenAI / Serper)
- Final artifacts (MD, PDF, email) are written to outputs/

##### Architectural Patterns & Design Principles
- Modular, pipeline-oriented design: each “crew” is an isolated stage
- Configuration-driven: YAML agent/task definitions allow swapping or extending behavior without code changes
- Single-process, service-oriented monolith (no microservices)
- Separation of concerns: UI vs. orchestration vs. AI logic vs. tooling

##### Technologies & Frameworks
- Python 3.12
- crewAI (for agent orchestration)
- Gradio (frontend)
- Docker & Docker-Compose (deployment)
- YAML (configuration)
- Third-party APIs: OpenAI, Serper

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and UI
    User["User"]:::user
    UI["Gradio UI\n(app.py)"]:::frontend

    User -->|"upload resume PDF<br>enter job URL"| UI
    UI -->|"inputs"| Orchestrator

    %% Orchestrator
    Orchestrator["Orchestrator\n(main.py)"]:::core

    UI --> Orchestrator

    %% Crews Group
    subgraph "Crews"
        direction TB
        subgraph "Tailor Resume Crew"
            direction TB
            t_py["tailor_resume_crew.py"]:::crew
            t_agents["agents.yaml"]:::config
            t_tasks["tasks.yaml"]:::config
        end
        subgraph "Companies Research Crew"
            direction TB
            c_py["companies_research_crew.py"]:::crew
            c_agents["agents.yaml"]:::config
            c_tasks["tasks.yaml"]:::config
        end
        subgraph "Email Writer Crew"
            direction TB
            e_py["email_writer_crew.py"]:::crew
            e_agents["agents.yaml"]:::config
            e_tasks["tasks.yaml"]:::config
        end
    end

    %% Tools Library
    subgraph "Tools Library"
        direction TB
        convert_pdf["convert_resume_to_pdf.py"]:::tools
        style_html["convert_to_styled_html.py"]:::tools
        custom_tool["custom_tool.py"]:::tools
        md_css["md-to-pdf.css"]:::config
    end

    %% External Services
    subgraph "External Services/APIs"
        direction TB
        openai["OpenAI API"]:::external
        serper["Serper API"]:::external
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        inputs["inputs/\n(base_resume.md)"]:::datastore
        outputs["outputs/"]:::datastore
    end

    %% Config & Dependencies
    subgraph "Config & Dependencies"
        direction TB
        env[".env.example"]:::config
        req["requirements.txt"]:::config
    end

    %% Deployment
    subgraph "Deployment"
        direction TB
        dockerfile["Dockerfile"]:::deploy
        compose["docker-compose.yml"]:::deploy
    end

    %% Data Flows
    Orchestrator -->|"PDF resume + URL"| t_py
    inputs --> t_py
    t_py -->|"calls OpenAI"| openai
    t_py --> convert_pdf
    t_py --> style_html
    convert_pdf --> outputs
    style_html --> outputs

    Orchestrator --> companies
    companies -->|"calls Serper"| serper
    companies -->|"calls OpenAI"| openai
    companies --> outputs

    Orchestrator --> email
    outputs --> email
    email -->|"calls OpenAI"| openai
    email --> outputs

    %% Deployment flows
    dockerfile --> UI
    dockerfile --> Orchestrator
    dockerfile --> convert_pdf
    dockerfile --> openai
    compose --> dockerfile

    %% Click Events
    click UI "https://github.com/rafacalassara/jobapplicationflow/blob/main/app.py"
    click Orchestrator "https://github.com/rafacalassara/jobapplicationflow/blob/main/main.py"
    click t_py "https://github.com/rafacalassara/jobapplicationflow/blob/main/crews/tailor_resume_crew/tailor_resume_crew.py"
    click t_agents "https://github.com/rafacalassara/jobapplicationflow/blob/main/crews/tailor_resume_crew/config/agents.yaml"
    click t_tasks "https://github.com/rafacalassara/jobapplicationflow/blob/main/crews/tailor_resume_crew/config/tasks.yaml"
    click c_py "https://github.com/rafacalassara/jobapplicationflow/blob/main/crews/companies_research_crew/companies_research_crew.py"
    click c_agents "https://github.com/rafacalassara/jobapplicationflow/blob/main/crews/companies_research_crew/config/agents.yaml"
    click c_tasks "https://github.com/rafacalassara/jobapplicationflow/blob/main/crews/companies_research_crew/config/tasks.yaml"
    click e_py "https://github.com/rafacalassara/jobapplicationflow/blob/main/crews/email_writer_crew/email_writer_crew.py"
    click e_agents "https://github.com/rafacalassara/jobapplicationflow/blob/main/crews/email_writer_crew/config/agents.yaml"
    click e_tasks "https://github.com/rafacalassara/jobapplicationflow/blob/main/crews/email_writer_crew/config/tasks.yaml"
    click convert_pdf "https://github.com/rafacalassara/jobapplicationflow/blob/main/tools/convert_resume_to_pdf.py"
    click style_html "https://github.com/rafacalassara/jobapplicationflow/blob/main/tools/convert_to_styled_html.py"
    click custom_tool "https://github.com/rafacalassara/jobapplicationflow/blob/main/tools/custom_tool.py"
    click inputs "https://github.com/rafacalassara/jobapplicationflow/tree/main/inputs/"
    click dockerfile "https://github.com/rafacalassara/jobapplicationflow/tree/main/Dockerfile"
    click compose "https://github.com/rafacalassara/jobapplicationflow/blob/main/docker-compose.yml"
    click env "https://github.com/rafacalassara/jobapplicationflow/blob/main/.env.example"
    click req "https://github.com/rafacalassara/jobapplicationflow/blob/main/requirements.txt"

    %% Styles
    classDef user fill:#FFD966,stroke:#E69A2E,color:#000
    classDef frontend fill:#9FC5E8,stroke:#2E75B6,color:#000
    classDef core fill:#B6D7A8,stroke:#6AA84F,color:#000
    classDef crew fill:#F4CCCC,stroke:#CC0000,color:#000
    classDef tools fill:#D9EAD3,stroke:#38761D,color:#000
    classDef external fill:#C9C9FF,stroke:#0000A0,color:#000
    classDef datastore fill:#FFF2CC,stroke:#E69138,color:#000
    classDef config fill:#EAD1DC,stroke:#A64D79,color:#000
    classDef deploy fill:#D5A6BD,stroke:#741B47,color:#000
```
