# catothi/cai-case-study architecture

> Architecture diagram of the GitHub repository catothi/cai-case-study, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/catothi/cai-case-study
- Repository: https://github.com/catothi/cai-case-study

## Overview

##### Project Type and Purpose
- This is a backend‐only, RESTful web service (“Restaurant Reservation API”) built with Flask and backed by PostgreSQL.
- Its sole responsibility is to expose HTTP endpoints for creating, updating, deleting, and querying table reservations.

##### File‐Structure Analysis
Top‐level “Case Study 1 – Postgres” directory contains:
- .env template – holds database credentials
- requirements.txt – Python dependencies (Flask, psycopg2 or SQLAlchemy, pytest, python‐dotenv)
- Postman/ – API request collection and a truncate script
- database_setup/ – DDL SQL script (`script.sql`) and a truncate helper
- src/ – two variants of the application entry points:
– app.py (raw SQL via psycopg2)
– app_with_orm.py (SQLAlchemy ORM)
- tests/ – pytest suite for API endpoints
Key patterns:
- Single Flask process serving all endpoints (no microservices)
- Clear separation of configuration, schema, application code, and tests

##### README Insights
- Describes prerequisites (Python, PostgreSQL, etc.) and setup steps: virtualenv, `.env`, DDL script.
- Lists 5 core endpoints under `/api/v1/`: tables, reservations CRUD, occupancy query.
- Advises on running the app (`python app.py`) and testing (`pytest`).
- Mentions Postman collection for manual testing and truncate scripts for cleaning DB.

##### Main Components & Relationships
a. API Client Layer
- Postman / web or mobile client – issues HTTP requests to the Flask service
b. Flask Application Layer
- app.py / app_with_orm.py – defines routes, request parsing, response formatting
- Configuration Loader – reads `.env` (DB_HOST, DB_USER, etc.)
- Business Logic – validates input, builds SQL queries or ORM calls
c. Data Access Layer
- psycopg2 driver OR SQLAlchemy ORM – executes queries, manages transactions
d. Database Layer
- PostgreSQL instance – holds `tables`, `customers`, `reservations`
- DDL script – initializes schema
- Truncate scripts – reset data for tests/dev
e. Testing Layer
- pytest framework – runs integration tests against the running Flask app & DB
f. External Tooling
- Postman collection for manual API exploration
- Git (implied for version control)

Relationships & Data Flow:
Client → HTTP Request → Flask App → (Business Logic → Data Access) → PostgreSQL
PostgreSQL → Query Result → Data Access → Business Logic → HTTP Response → Client
DDL/Truncate Scripts → PostgreSQL (for setup/teardown)
pytest → Flask App + PostgreSQL (for test verification)

##### Architectural Patterns & Principles
- Separation of Concerns: configuration, routing, business logic, data access, testing
- Layered Architecture: Presentation (HTTP), Application Logic, Persistence, Database
- 12-Factor App elements: environment config, dependency declaration, backing services

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Configuration"
        Env[".env"]:::config
        Req["requirements.txt"]:::config
    end

    subgraph "Database Setup"
        DDL["script.sql"]:::dbsetup
        DTrunc["truncate.py"]:::dbsetup
    end

    subgraph "Runtime Services"
        subgraph "Flask Application"
            RawApp["app.py (raw SQL)"]:::service
            OrmApp["app_with_orm.py (ORM)"]:::service
            ConfigLoader["Configuration Loader"]:::module
            BizLogic["Business Logic"]:::module
            DataAccess["Data Access"]:::module
        end
        DB["PostgreSQL DB"]:::db
    end

    subgraph "Clients & Testing"
        Postman["Postman Collection"]:::external
        PMTrunc["Postman Truncate Script"]:::external
        Pytest["pytest Tests"]:::external
        Cache["__pycache__"]:::external
    end

    Env -->|loads| ConfigLoader
    Req -->|dependencies| RawApp
    Req -->|dependencies| OrmApp

    ConfigLoader -->|injects config| RawApp
    ConfigLoader -->|injects config| OrmApp

    RawApp -->|invokes| BizLogic
    OrmApp -->|invokes| BizLogic

    BizLogic -->|calls| DataAccess
    DataAccess -->|queries| DB
    DB -->|returns data| DataAccess
    DataAccess -->|returns results| BizLogic
    BizLogic -->|formats response| RawApp
    BizLogic -->|formats response| OrmApp

    Postman -->|HTTP requests| RawApp
    Postman -->|HTTP requests| OrmApp
    PMTrunc -->|API reset| RawApp
    Pytest -->|integration tests| RawApp
    Pytest -->|integration tests| OrmApp
    Pytest -->|uses DB| DB
    Pytest -->|stores cache| Cache

    DDL -.->|setup schema| DB
    DTrunc -.->|teardown data| DB

    click Env "https://github.com/catothi/cai-case-study/blob/main/Case Study 1 - Postgres/.env"
    click Req "https://github.com/catothi/cai-case-study/blob/main/Case Study 1 - Postgres/requirements.txt"
    click Postman "https://github.com/catothi/cai-case-study/blob/main/Case Study 1 - Postgres/Postman/test.json"
    click PMTrunc "https://github.com/catothi/cai-case-study/blob/main/Case Study 1 - Postgres/Postman/truncate.py"
    click DDL "https://github.com/catothi/cai-case-study/blob/main/Case Study 1 - Postgres/database_setup/script.sql"
    click DTrunc "https://github.com/catothi/cai-case-study/blob/main/Case Study 1 - Postgres/database_setup/truncate.py"
    click RawApp "https://github.com/catothi/cai-case-study/blob/main/Case Study 1 - Postgres/src/app.py"
    click OrmApp "https://github.com/catothi/cai-case-study/blob/main/Case Study 1 - Postgres/src/app_with_orm.py"
    click Pytest "https://github.com/catothi/cai-case-study/blob/main/Case Study 1 - Postgres/tests/test.py"
    click Cache "https://github.com/catothi/cai-case-study/tree/main/Case Study 1 - Postgres/tests/__pycache__"

    classDef config fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef dbsetup fill:#e6e6e6,stroke:#333,stroke-width:1px
    classDef service fill:#d4edda,stroke:#333,stroke-width:1px
    classDef module fill:#d1ecf1,stroke:#333,stroke-width:1px
    classDef db fill:#c3e6cb,stroke:#333,stroke-width:1px
    classDef external fill:#ffe5cc,stroke:#333,stroke-width:1px
```
