# saedelbarshly/agentic-ai architecture

> Architecture diagram of the GitHub repository saedelbarshly/agentic-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saedelbarshly/agentic-ai
- Repository: https://github.com/saedelbarshly/agentic-ai

## Overview

AI CV & Job Analyzer accepts CV text and a job description, extracts a candidate profile, checks evidence sufficiency, analyzes job requirements, then routes to an application-ready report or gap review. The workflow also validates model-generated evidence; a failed CV gate returns needs_input before job analysis. The API maps provider failures to safe HTTP errors, and the Groq adapter supplies structured-output calls with retries. Edges reflect README statements and indexed or excerpted references; unsampled implementation details are not inferred.

Main entry points: [`app/services/workflow.py`](https://github.com/saedelbarshly/agentic-ai/blob/main/app/services/workflow.py) (Analysis workflow), [`app/api/routes/analysis.py`](https://github.com/saedelbarshly/agentic-ai/blob/main/app/api/routes/analysis.py) (Analysis endpoint), [`app/main.py`](https://github.com/saedelbarshly/agentic-ai/blob/main/app/main.py) (FastAPI application), [`app/providers/groq_provider.py`](https://github.com/saedelbarshly/agentic-ai/blob/main/app/providers/groq_provider.py) (Groq JSON provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API boundary"]
  node_analysis_api["Analysis endpoint<br/>[analysis.py]"]
  node_contracts["Request and response models<br/>[schemas.py]"]
end

subgraph group_workflow["Analysis workflow"]
  node_orchestrator["Analysis workflow<br/>[workflow.py]"]
  node_cv_extract["CV extraction<br/>[prompts.py]"]
  node_cv_gate["CV sufficiency gate<br/>[gates.py]"]
  node_job_analysis["Job analysis<br/>[prompts.py]"]
  node_job_gate["Required-match gate<br/>[gates.py]"]
  node_ready_report["Application-ready report<br/>[prompts.py]"]
  node_gap_report["Gap review<br/>[prompts.py]"]
  node_evidence_validation["Evidence validation<br/>[workflow.py]"]
end

subgraph group_provider["Model provider"]
  node_groq_adapter["Groq JSON provider<br/>[groq_provider.py]"]
  node_groq_service{{"Groq API"}}
end

subgraph group_runtime["Runtime support"]
  node_application["FastAPI application<br/>[main.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_logging["Logging setup<br/>[logging.py]"]
  node_provider_errors["Provider error types<br/>[errors.py]"]
end

node_client(("API client"))

node_client -->|"submits analysis"| node_analysis_api
node_analysis_api -->|"validates payload"| node_contracts
node_analysis_api -->|"runs workflow"| node_orchestrator
node_analysis_api -->|"provides dependency"| node_groq_adapter
node_analysis_api -->|"checks limits"| node_settings
node_orchestrator -->|"uses prompt"| node_cv_extract
node_orchestrator -->|"requests structured output"| node_groq_adapter
node_orchestrator -->|"validates profile"| node_cv_gate
node_orchestrator -->|"uses prompt"| node_job_analysis
node_orchestrator -->|"evaluates requirements"| node_job_gate
node_orchestrator -->|"uses prompt"| node_ready_report
node_orchestrator -->|"uses prompt"| node_gap_report
node_orchestrator -->|"validates evidence"| node_evidence_validation
node_orchestrator -->|"uses models"| node_contracts
node_groq_adapter -->|"reads credentials and limits"| node_settings
node_groq_adapter -->|"sends completion request"| node_groq_service
node_application -->|"mounts router"| node_analysis_api
node_application -->|"loads settings"| node_settings
node_application -->|"configures logging"| node_logging
node_application -->|"maps failures"| node_provider_errors
node_logging -->|"reads log level"| node_settings

click node_analysis_api "https://github.com/saedelbarshly/agentic-ai/blob/main/app/api/routes/analysis.py"
click node_contracts "https://github.com/saedelbarshly/agentic-ai/blob/main/app/schemas.py"
click node_orchestrator "https://github.com/saedelbarshly/agentic-ai/blob/main/app/services/workflow.py"
click node_cv_extract "https://github.com/saedelbarshly/agentic-ai/blob/main/app/prompts.py"
click node_cv_gate "https://github.com/saedelbarshly/agentic-ai/blob/main/app/services/gates.py"
click node_job_analysis "https://github.com/saedelbarshly/agentic-ai/blob/main/app/prompts.py"
click node_job_gate "https://github.com/saedelbarshly/agentic-ai/blob/main/app/services/gates.py"
click node_ready_report "https://github.com/saedelbarshly/agentic-ai/blob/main/app/prompts.py"
click node_gap_report "https://github.com/saedelbarshly/agentic-ai/blob/main/app/prompts.py"
click node_evidence_validation "https://github.com/saedelbarshly/agentic-ai/blob/main/app/services/workflow.py"
click node_groq_adapter "https://github.com/saedelbarshly/agentic-ai/blob/main/app/providers/groq_provider.py"
click node_application "https://github.com/saedelbarshly/agentic-ai/blob/main/app/main.py"
click node_settings "https://github.com/saedelbarshly/agentic-ai/blob/main/app/core/config.py"
click node_logging "https://github.com/saedelbarshly/agentic-ai/blob/main/app/core/logging.py"
click node_provider_errors "https://github.com/saedelbarshly/agentic-ai/blob/main/app/core/errors.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_analysis_api,node_contracts,node_client toneBlue
class node_orchestrator,node_cv_extract,node_cv_gate,node_job_analysis,node_job_gate,node_ready_report,node_gap_report,node_evidence_validation toneAmber
class node_groq_adapter,node_groq_service toneMint
class node_application,node_settings,node_logging,node_provider_errors toneRose
```

## Components

### API boundary

- [Analysis endpoint](https://github.com/saedelbarshly/agentic-ai/blob/main/app/api/routes/analysis.py): `app/api/routes/analysis.py`
- [Request and response models](https://github.com/saedelbarshly/agentic-ai/blob/main/app/schemas.py): `app/schemas.py`

### Analysis workflow

- [Analysis workflow](https://github.com/saedelbarshly/agentic-ai/blob/main/app/services/workflow.py): `app/services/workflow.py`
- [CV extraction](https://github.com/saedelbarshly/agentic-ai/blob/main/app/prompts.py): `app/prompts.py`
- [CV sufficiency gate](https://github.com/saedelbarshly/agentic-ai/blob/main/app/services/gates.py): `app/services/gates.py`
- [Job analysis](https://github.com/saedelbarshly/agentic-ai/blob/main/app/prompts.py): `app/prompts.py`
- [Required-match gate](https://github.com/saedelbarshly/agentic-ai/blob/main/app/services/gates.py): `app/services/gates.py`
- [Application-ready report](https://github.com/saedelbarshly/agentic-ai/blob/main/app/prompts.py): `app/prompts.py`
- [Gap review](https://github.com/saedelbarshly/agentic-ai/blob/main/app/prompts.py): `app/prompts.py`
- [Evidence validation](https://github.com/saedelbarshly/agentic-ai/blob/main/app/services/workflow.py): `app/services/workflow.py`

### Model provider

- [Groq JSON provider](https://github.com/saedelbarshly/agentic-ai/blob/main/app/providers/groq_provider.py): `app/providers/groq_provider.py`
- **Groq API**

### Runtime support

- [FastAPI application](https://github.com/saedelbarshly/agentic-ai/blob/main/app/main.py): `app/main.py`
- [Runtime settings](https://github.com/saedelbarshly/agentic-ai/blob/main/app/core/config.py): `app/core/config.py`
- [Logging setup](https://github.com/saedelbarshly/agentic-ai/blob/main/app/core/logging.py): `app/core/logging.py`
- [Provider error types](https://github.com/saedelbarshly/agentic-ai/blob/main/app/core/errors.py): `app/core/errors.py`

### Other components

- **API client**

## Connections

- API client → Analysis endpoint: submits analysis (evidence: `README.md`)
- Analysis endpoint → Request and response models: validates payload (evidence: `app/api/routes/analysis.py`)
- Analysis endpoint → Analysis workflow: runs workflow (evidence: `app/api/routes/analysis.py`)
- Analysis endpoint → Groq JSON provider: provides dependency (evidence: `app/api/routes/analysis.py`)
- Analysis endpoint → Runtime settings: checks limits (evidence: `app/api/routes/analysis.py`)
- Analysis workflow → CV extraction: uses prompt (evidence: `app/services/workflow.py`)
- Analysis workflow → Groq JSON provider: requests structured output (evidence: `app/services/workflow.py`)
- Analysis workflow → CV sufficiency gate: validates profile (evidence: `app/services/workflow.py`)
- Analysis workflow → Job analysis: uses prompt (evidence: `app/services/workflow.py`)
- Analysis workflow → Required-match gate: evaluates requirements (evidence: `app/services/workflow.py`)
- Analysis workflow → Application-ready report: uses prompt (evidence: `app/services/workflow.py`)
- Analysis workflow → Gap review: uses prompt (evidence: `app/services/workflow.py`)
- Analysis workflow → Evidence validation: validates evidence (evidence: `app/services/workflow.py`)
- Analysis workflow → Request and response models: uses models (evidence: `app/services/workflow.py`)
- Groq JSON provider → Runtime settings: reads credentials and limits (evidence: `app/providers/groq_provider.py`)
- Groq JSON provider → Groq API: sends completion request (evidence: `app/providers/groq_provider.py`)
- FastAPI application → Analysis endpoint: mounts router (evidence: `app/main.py`)
- FastAPI application → Runtime settings: loads settings (evidence: `app/main.py`)
- FastAPI application → Logging setup: configures logging (evidence: `app/main.py`)
- FastAPI application → Provider error types: maps failures (evidence: `app/main.py`)
- Logging setup → Runtime settings: reads log level (evidence: `app/core/logging.py`)
