How catothi/cai-case-study works
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