# jeanmilpied/raizuum-api architecture

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

- Interactive diagram: https://gitdiagram.com/jeanmilpied/raizuum-api
- Repository: https://github.com/jeanmilpied/raizuum-api

## Overview

##### Project Type and Purpose
- The project is an API service (backend) that processes CV files. It exposes endpoints for OCR extraction and feature extraction from PDFs.
- It uses a FastAPI framework, provides OAuth2-based authentication, and makes use of data models and utility modules to perform text extraction and feature scoring.

##### Analyzing the File Structure
- The top-level “app” directory contains the main application code:
- Main entry point is app/main.py.
- The “routes” directory holds endpoints: “auth.py” covers authentication while “ocr.py” is dedicated to OCR processing.
- The “services” directory encapsulates business logic for authentication and OCR processes.
- The “models” directory defines data structures like OCRRequest and UserModel which likely utilize pydantic for request/response schemas.
- The “utils” directory provides helper modules (extractors, nlp_utils, scoring, security) to support the main services.
- Infrastructure files such as Dockerfile, docker-compose.yml, and environment settings in .env indicate containerization, deployment configuration, and environment-based settings.
- The setup_project.py and requirements.txt handle project setup and library dependencies.

a. Main Components:
- Client / Consumer:
- The user or client making HTTP requests to the API.
- Interactions coming through browsers (Swagger UI) or via cURL/Postman.
- Web Server / API Gateway:
- The FastAPI application (app/main.py) that acts as the entry point.
- Incorporate external view of Docker containerized service (Dockerfile & docker-compose.yml).
- API Endpoints:
- Authentication Endpoint (via app/routes/auth.py): handling OAuth2 token generation.
- OCR/Extraction Endpoints (via app/routes/ocr.py): handling file uploads (/extract-from-pdf) and text feature extraction (/extract-features).
- Business Logic Layer:
- Services (app/services/auth_service.py and app/services/ocr_service.py) that encapsulate core logic.
- Data Models:
- Models (app/models/ocr_request.py and app/models/user_model.py) defining the data structures for requests, responses, and internal processing.
- Utilities and Helpers:
- Utility modules (app/utils/*.py) responsible for OCR text extraction, NLP analysis, scoring, and additional security routines.

b. Relationships and Data Flow:
- The Client issues API requests (with valid OAuth2 tokens) to the FastAPI server.
- Requests hit the relevant API endpoint (e.g., upload a PDF to /extract-from-pdf/).
- Endpoints invoke the corresponding service in the “services” layer (OCR or Authentication service).
- Services process the request using helper functions from the “utils” directory and validate/convert data using models.
- Processed data and responses flow back from services to the API endpoints and then return to the Client.

c. Architectural Patterns and Design Principles:
- Separation of Concerns: Routes are solely responsible for request/response handling while business logic resides in services, and helper functions are in utilities.
- Layered Architecture: Clear division between API routes, service layer, and utility modules.
- Containerization: Dockerfile and docker-compose indicate that the entire system is containerized, which should be represented as an infrastructure boundary.

d. Technologies, Frameworks, and Libraries:
- FastAPI as the web framework.
- Python (with libraries for OCR, NLP, and OAuth2).
- Docker for containerization and deployment.
- Potential use of Pydantic models in the models directory for data schema validation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Client
    Client["Client/Consumer"]:::client

    %% Containerized FastAPI Application
    subgraph "FastAPI Container (Docker)"
        APPSVR["FastAPI Server (app/main.py)"]:::server
        %% API Endpoints Layer
        subgraph "API Endpoints"
            AuthEP["Auth Endpoint (/login, etc)"]:::api
            OCREP["OCR Endpoint (/extract-from-pdf, /extract-features)"]:::api
        end
        %% Business Logic (Services) Layer
        subgraph "Business Logic (Services)"
            AuthService["Auth Service"]:::service
            OCRService["OCR Service"]:::service
        end
        %% Data Models Layer
        subgraph "Data Models"
            OCRModel["OCR Request Model"]:::model
            UserModel["User Model"]:::model
        end
        %% Utility Modules Layer
        subgraph "Utility Modules"
            Extractors["Extractors Module"]:::util
            NLPUtils["NLP Utils Module"]:::util
            Scoring["Scoring Module"]:::util
            Security["Security Module"]:::util
        end
    end

    %% Deployment & Setup Infrastructure
    subgraph "Deployment & Setup"
        Docker["Dockerfile"]:::deploy
        DockerCompose["docker-compose.yml"]:::deploy
        Env[".env"]:::deploy
        Setup["setup_project.py"]:::deploy
        Requirements["requirements.txt"]:::deploy
    end

    %% Data Flow Arrows
    Client -->|"APIRequest"| APPSVR
    APPSVR -->|"routes"| AuthEP
    APPSVR -->|"routes"| OCREP
    AuthEP -->|"calls"| AuthService
    OCREP -->|"calls"| OCRService
    AuthService -->|"validates"| UserModel
    OCRService -->|"validates"| OCRModel
    AuthService -->|"uses"| Security
    OCRService -->|"uses"| Extractors
    OCRService -->|"uses"| NLPUtils
    OCRService -->|"uses"| Scoring

    %% Deployment Relationships
    APPSVR -->|"deployedVia"| Docker
    APPSVR -->|"configuredBy"| DockerCompose
    APPSVR -->|"envConfigured"| Env
    APPSVR -->|"setupScript"| Setup
    APPSVR -->|"dependencies"| Requirements

    %% Class Definitions for Colors
    classDef client fill:#CEF6F5,stroke:#036,stroke-width:2px;
    classDef server fill:#C1FFC1,stroke:#333,stroke-width:2px;
    classDef api fill:#FFD1DC,stroke:#333,stroke-width:2px;
    classDef service fill:#FFDEAD,stroke:#333,stroke-width:2px;
    classDef model fill:#FFFFCC,stroke:#333,stroke-width:2px;
    classDef util fill:#E6E6FA,stroke:#333,stroke-width:2px;
    classDef deploy fill:#D3D3D3,stroke:#333,stroke-width:2px;

    %% Click Events for Component Mappings
    click APPSVR "https://github.com/jeanmilpied/raizuum-api/blob/main/app/main.py"
    click AuthEP "https://github.com/jeanmilpied/raizuum-api/blob/main/app/routes/auth.py"
    click OCREP "https://github.com/jeanmilpied/raizuum-api/blob/main/app/routes/ocr.py"
    click AuthService "https://github.com/jeanmilpied/raizuum-api/blob/main/app/services/auth_service.py"
    click OCRService "https://github.com/jeanmilpied/raizuum-api/blob/main/app/services/ocr_service.py"
    click OCRModel "https://github.com/jeanmilpied/raizuum-api/blob/main/app/models/ocr_request.py"
    click UserModel "https://github.com/jeanmilpied/raizuum-api/blob/main/app/models/user_model.py"
    click Extractors "https://github.com/jeanmilpied/raizuum-api/blob/main/app/utils/extractors.py"
    click NLPUtils "https://github.com/jeanmilpied/raizuum-api/blob/main/app/utils/nlp_utils.py"
    click Scoring "https://github.com/jeanmilpied/raizuum-api/blob/main/app/utils/scoring.py"
    click Security "https://github.com/jeanmilpied/raizuum-api/blob/main/app/utils/security.py"
    click Docker "https://github.com/jeanmilpied/raizuum-api/tree/main/Dockerfile"
    click DockerCompose "https://github.com/jeanmilpied/raizuum-api/blob/main/docker-compose.yml"
    click Env "https://github.com/jeanmilpied/raizuum-api/blob/main/.env"
    click Setup "https://github.com/jeanmilpied/raizuum-api/blob/main/setup_project.py"
    click Requirements "https://github.com/jeanmilpied/raizuum-api/blob/main/requirements.txt"
```
