# ahmedmontaser123/flow_wise_platform architecture

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

- Interactive diagram: https://gitdiagram.com/ahmedmontaser123/flow_wise_platform
- Repository: https://github.com/ahmedmontaser123/flow_wise_platform

## Overview

FlowWise is a recruitment backend whose implemented user workflow accepts and validates project-organized CV uploads, then supports PDF text extraction and schema-validated LLM extraction. Its README also describes repository-backed recruitment data management. The graph preserves those domain stages and the documented API, storage, and database layers. Some matching, workflow, and analytics capabilities are explicitly planned, not implemented; source excerpts do not establish all runtime wiring, so uncertain links are omitted.

Main entry points: [`src/controllers/process_controller.py`](https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/controllers/process_controller.py) (PDF extraction), [`src/stores/LLM/LLMProviderFactory.py`](https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/stores/LLM/LLMProviderFactory.py) (Provider factory), [`src/repositories`](https://github.com/ahmedmontaser123/flow_wise_platform/tree/main/src/repositories) (Entity repositories), [`src/main.py`](https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and CV intake"]
  node_app["FastAPI app<br/>[main.py]"]
  node_cv_routes["CV routes<br/>[cv_router.py]"]
  node_cv_validation["CV validation<br/>[cv_controller.py]"]
end

subgraph group_processing["CV processing"]
  node_project_storage[("Project file storage")]
  node_pdf_processing["PDF extraction"]
  node_parsed_schema["Parsed CV schema"]
  node_json_extract["JSON extraction<br/>[json_utils.py]"]
end

subgraph group_ai["LLM integration"]
  node_llm_factory["Provider factory"]
  node_llm_interface["Generation interface<br/>[LLMInterface.py]"]
  node_cohere["Cohere provider<br/>[CohereProvider.py]"]
  node_groq["Groq provider<br/>[GroqProvider.py]"]
  node_huggingface["HuggingFace provider"]
end

subgraph group_data["Recruitment data"]
  node_repositories["Entity repositories"]
  node_recruitment_schema["Recruitment models"]
  node_database[("PostgreSQL database")]
  node_business_schemas["API data schemas"]
end

node_client(("HR client"))

node_client -->|"sends request"| node_app
node_app -->|"registers routes"| node_cv_routes
node_cv_routes -->|"dispatches upload"| node_cv_validation
node_cv_validation -->|"gets project path"| node_project_storage
node_pdf_processing -->|"resolves project files"| node_project_storage
node_pdf_processing -->|"extracts JSON"| node_json_extract
node_pdf_processing -->|"validates parsed data"| node_parsed_schema
node_pdf_processing -->|"calls generation methods"| node_llm_interface
node_app -->|"creates provider factory"| node_llm_factory
node_llm_factory -->|"selects provider"| node_cohere
node_llm_factory -->|"selects provider"| node_groq
node_llm_factory -->|"selects provider"| node_huggingface
node_repositories -->|"persists entities"| node_database
node_repositories -->|"uses models"| node_recruitment_schema
node_repositories -->|"uses API schemas"| node_business_schemas

click node_app "https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/main.py"
click node_cv_routes "https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/routes/cv_router.py"
click node_cv_validation "https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/controllers/cv_controller.py"
click node_project_storage "https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/controllers/project_controller.py"
click node_pdf_processing "https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/controllers/process_controller.py"
click node_parsed_schema "https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/schema/cv_parsed_schema.py"
click node_json_extract "https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/helpers/json_utils.py"
click node_llm_factory "https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/stores/LLM/LLMProviderFactory.py"
click node_llm_interface "https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/stores/LLM/LLMInterface.py"
click node_cohere "https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/stores/LLM/providers/CohereProvider.py"
click node_groq "https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/stores/LLM/providers/GroqProvider.py"
click node_huggingface "https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/stores/LLM/providers/HuggingFaceProvider.py"
click node_repositories "https://github.com/ahmedmontaser123/flow_wise_platform/tree/main/src/repositories"
click node_recruitment_schema "https://github.com/ahmedmontaser123/flow_wise_platform/tree/main/src/models/db/flow_wise/schema"
click node_database "https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/models/db/connection_database.py"
click node_business_schemas "https://github.com/ahmedmontaser123/flow_wise_platform/tree/main/src/schema"

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_app,node_cv_routes,node_cv_validation,node_client toneBlue
class node_project_storage,node_pdf_processing,node_parsed_schema,node_json_extract toneAmber
class node_llm_factory,node_llm_interface,node_cohere,node_groq,node_huggingface toneMint
class node_repositories,node_recruitment_schema,node_database,node_business_schemas toneRose
```

## Components

### API and CV intake

- [FastAPI app](https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/main.py): `src/main.py`
- [CV routes](https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/routes/cv_router.py): `src/routes/cv_router.py`
- [CV validation](https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/controllers/cv_controller.py): `src/controllers/cv_controller.py`

### CV processing

- [Project file storage](https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/controllers/project_controller.py): `src/controllers/project_controller.py`
- [PDF extraction](https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/controllers/process_controller.py): `src/controllers/process_controller.py`
- [Parsed CV schema](https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/schema/cv_parsed_schema.py): `src/schema/cv_parsed_schema.py`
- [JSON extraction](https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/helpers/json_utils.py): `src/helpers/json_utils.py`

### LLM integration

- [Provider factory](https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/stores/LLM/LLMProviderFactory.py): `src/stores/LLM/LLMProviderFactory.py`
- [Generation interface](https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/stores/LLM/LLMInterface.py): `src/stores/LLM/LLMInterface.py`
- [Cohere provider](https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/stores/LLM/providers/CohereProvider.py): `src/stores/LLM/providers/CohereProvider.py`
- [Groq provider](https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/stores/LLM/providers/GroqProvider.py): `src/stores/LLM/providers/GroqProvider.py`
- [HuggingFace provider](https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/stores/LLM/providers/HuggingFaceProvider.py): `src/stores/LLM/providers/HuggingFaceProvider.py`

### Recruitment data

- [Entity repositories](https://github.com/ahmedmontaser123/flow_wise_platform/tree/main/src/repositories): `src/repositories`
- [Recruitment models](https://github.com/ahmedmontaser123/flow_wise_platform/tree/main/src/models/db/flow_wise/schema): `src/models/db/flow_wise/schema`
- [PostgreSQL database](https://github.com/ahmedmontaser123/flow_wise_platform/blob/main/src/models/db/connection_database.py): `src/models/db/connection_database.py`
- [API data schemas](https://github.com/ahmedmontaser123/flow_wise_platform/tree/main/src/schema): `src/schema`

### Other components

- **HR client**

## Connections

- HR client → FastAPI app: sends request
- FastAPI app → CV routes: registers routes (evidence: `src/main.py`)
- CV routes → CV validation: dispatches upload (evidence: `src/routes/cv_router.py`)
- CV validation → Project file storage: gets project path (evidence: `src/controllers/cv_controller.py`)
- PDF extraction → Project file storage: resolves project files (evidence: `src/controllers/process_controller.py`)
- PDF extraction → JSON extraction: extracts JSON (evidence: `src/controllers/process_controller.py`)
- PDF extraction → Parsed CV schema: validates parsed data (evidence: `src/controllers/process_controller.py`)
- PDF extraction → Generation interface: calls generation methods (evidence: `src/controllers/process_controller.py`)
- FastAPI app → Provider factory: creates provider factory (evidence: `src/main.py`)
- Provider factory → Cohere provider: selects provider (evidence: `src/stores/LLM/LLMProviderFactory.py`)
- Provider factory → Groq provider: selects provider (evidence: `src/stores/LLM/LLMProviderFactory.py`)
- Provider factory → HuggingFace provider: selects provider (evidence: `src/stores/LLM/LLMProviderFactory.py`)
- Entity repositories → PostgreSQL database: persists entities
- Entity repositories → Recruitment models: uses models (evidence: `src/repositories/candidate_repository.py`)
- Entity repositories → API data schemas: uses API schemas (evidence: `src/repositories/candidate_repository.py`)
