# lharroyo/pythonrest architecture

> Architecture diagram of the GitHub repository lharroyo/pythonrest, 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/lharroyo/pythonrest
- Repository: https://github.com/lharroyo/pythonrest

## Overview

##### Project type and purpose
- This is a backend-only RESTful API for managing Departments, Hired Employees, and Jobs.
- Built in Python with Flask (HTTP layer), SQLAlchemy (ORM), and Pandas (bulk CSV import).

##### High-level file structure analysis
- Top-level:
- Dockerfile, .env, requirements.txt → deployment & env configuration
- main.py (app bootstrap) and dashexample.py (optional dashboard script)
- controllers/ → HTTP route definitions (Flask Blueprints)
- services/ → business logic & orchestration (data validation, Pandas CSV handling)
- models/ → SQLAlchemy ORM table definitions
- data/ → sample CSVs and LoadData.py utility
- Readme.md → usage, endpoints, tech stack

##### Core components
a. Clients & API Gateway
- External consumer (curl, Postman, frontend app)
- HTTP(S) requests hit Flask API
b. Presentation Layer
- Flask app (main.py)
- Controllers (DepartmentsController, HiredEmployeesController, JobsController, root)
c. Business Layer
- Services (DepartmentsService, HiredEmployeesService, JobsService)
- Bulk-import utility (LoadData.py using Pandas)
d. Data Access Layer
- Models (DepartmentModel, HiredEmployeesModel, JobModel, base.py)
- SQLAlchemy Session & engine
e. Persistence & Storage
- Relational Database (PostgreSQL/MySQL/SQLite configured via .env)
- File storage for uploaded CSVs (local disk or Azure Blob)
- Static CSVs in data/ for seed or testing
f. Infrastructure
- Docker container
- Hosting platform (Azure Web App)

##### Relationships & data flows
1. Client → HTTP request → Flask controller (route handler)
2. Controller → invokes appropriate Service method → applies business rules
3. Service → uses SQLAlchemy models to query/update DB or uses Pandas to bulk-load CSV into DB
4. Service → returns domain object or status → Controller → serializes to JSON → HTTP response
5. For file uploads: Controller accepts multipart/form-data → Service writes CSV to disk and processes via LoadData.py → persists records

##### Architectural patterns and principles
- Layered (Controller → Service → Data Access)
- Separation of concerns:
- Controllers only handle HTTP & request parsing
- Services encapsulate all logic & orchestrations
- Models only declare DB schema
- Dependency injection via passing the DB session (SQLAlchemy) into services
- Bulk data import pattern using Pandas
- 12-Factor App compliance (configuration in .env, logs to stdout, containerized)

##### Final checklist
- All components labeled with name + technology
- Clear grouping (e.g., boundary around “Flask App Container”)
- A title and version/date annotation

## Diagram (Mermaid)

```mermaid
flowchart TB
    Client["External Client\n(curl, Postman)"]:::external

    subgraph "Flask App Container"
        subgraph "Presentation Layer\n(Flask API)"
            main["main.py\n(Flask App Entry)"]:::api
            rootCtrl["root.py\n(Root Controller)"]:::controllers
            deptsCtrl["DepartmentsController.py"]:::controllers
            hiredCtrl["HiredEmployeesController.py"]:::controllers
            jobsCtrl["JobsController.py"]:::controllers
        end
        subgraph "Business Layer\n(Services)"
            deptService["DepartmentsService.py"]:::services
            hiredService["HiredEmployeesService.py"]:::services
            jobsService["JobsService.py"]:::services
            loadUtil["LoadData.py\n(CSV Loader)"]:::services
        end
        subgraph "Data Access Layer\n(ORM Models)"
            baseModel["base.py"]:::models
            deptModel["DepartmentModel.py"]:::models
            hiredModel["HiredEmployeesModel.py"]:::models
            jobModel["JobModel.py"]:::models
        end
        dashex["dashexample.py\n(Optional Dashboard)"]:::infra
    end

    db["Relational Database\n(PostgreSQL/MySQL)"]:::external
    fileStorage["File Storage\n(local disk / Azure Blob)"]:::external
    sampleCsvs["Static CSV Files\n(data/*.csv)"]:::external
    config[".env\nrequirements.txt\nDockerfile"]:::infra
    doc["Readme.md"]:::infra
    azure["Azure Web App"]:::external

    Client -->|"HTTP Request"| main
    main --> rootCtrl
    main --> deptsCtrl
    main --> hiredCtrl
    main --> jobsCtrl

    rootCtrl -->|"calls"| deptService
    rootCtrl -->|"calls"| hiredService
    rootCtrl -->|"calls"| jobsService

    deptsCtrl -->|"calls"| deptService
    hiredCtrl -->|"calls"| hiredService
    jobsCtrl -->|"calls"| jobsService

    deptService -->|"uses ORM"| deptModel
    hiredService -->|"uses ORM"| hiredModel
    jobsService -->|"uses ORM"| jobModel

    deptService -->|"bulk CSV process"| loadUtil
    hiredService -->|"bulk CSV process"| loadUtil
    jobsService -->|"bulk CSV process"| loadUtil

    loadUtil -.->|"reads"| sampleCsvs
    loadUtil -.->|"writes to"| fileStorage
    loadUtil -->|"persists via ORM"| baseModel

    deptModel -->|"SQL queries"| db
    hiredModel -->|"SQL queries"| db
    jobModel -->|"SQL queries"| db

    fileStorage -.->|"multipart uploads"| deptsCtrl
    fileStorage -.->|"multipart uploads"| hiredCtrl
    fileStorage -.->|"multipart uploads"| jobsCtrl

    config -->|"env vars injected"| main
    main -->|"containerized"| azure
    dashex -->|"reads from"| db

    %% Click Events
    click main "https://github.com/lharroyo/pythonrest/blob/main/main.py"
    click rootCtrl "https://github.com/lharroyo/pythonrest/blob/main/controllers/root.py"
    click deptsCtrl "https://github.com/lharroyo/pythonrest/blob/main/controllers/DepartmentsController.py"
    click hiredCtrl "https://github.com/lharroyo/pythonrest/blob/main/controllers/HiredEmployeesController.py"
    click jobsCtrl "https://github.com/lharroyo/pythonrest/blob/main/controllers/JobsController.py"
    click deptService "https://github.com/lharroyo/pythonrest/blob/main/services/DepartmentsService.py"
    click hiredService "https://github.com/lharroyo/pythonrest/blob/main/services/HiredEmployeesService.py"
    click jobsService "https://github.com/lharroyo/pythonrest/blob/main/services/JobsService.py"
    click loadUtil "https://github.com/lharroyo/pythonrest/blob/main/data/LoadData.py"
    click baseModel "https://github.com/lharroyo/pythonrest/blob/main/models/base.py"
    click deptModel "https://github.com/lharroyo/pythonrest/blob/main/models/DepartmentModel.py"
    click hiredModel "https://github.com/lharroyo/pythonrest/blob/main/models/HiredEmployeesModel.py"
    click jobModel "https://github.com/lharroyo/pythonrest/blob/main/models/JobModel.py"
    click sampleCsvs "https://github.com/lharroyo/pythonrest/tree/main/data"
    click dashex "https://github.com/lharroyo/pythonrest/blob/main/dashexample.py"
    click config "https://github.com/lharroyo/pythonrest/blob/main/.env"
    click config "https://github.com/lharroyo/pythonrest/blob/main/requirements.txt"
    click config "https://github.com/lharroyo/pythonrest/tree/main/Dockerfile"
    click doc "https://github.com/lharroyo/pythonrest/blob/main/Readme.md"

    classDef controllers fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef services fill:#90EE90,stroke:#000,stroke-width:1px
    classDef models fill:#FFD700,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef api fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef infra fill:#DCDCDC,stroke:#000,stroke-width:1px
```
