# lemansachs29/fairtip-api architecture

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

- Interactive diagram: https://gitdiagram.com/lemansachs29/fairtip-api
- Repository: https://github.com/lemansachs29/fairtip-api

## Overview

1. Fairtip is a backend-first REST API built with Flask, SQLAlchemy, and PostgreSQL. The repository is organized around a small set of business domains: users/auth, employees, recurring day offs, absences, and tip distributions.

2. The application entry point is `run.py`, which boots the Flask app defined under `app/`. The app package is split into configuration, extension initialization, HTTP routes, domain models, and at least one service layer for business logic.

3. `app/config.py` and `app/extensions.py` act as infrastructure boundaries. They centralize environment-driven settings and shared Flask extensions such as the database layer and authentication support, so the rest of the code stays focused on domain behavior.

4. The HTTP/API layer lives in `app/routes/` and is divided by resource: `auth`, `employees`, `absences`, and `distributions`. These route modules are the request/response boundary of the system and are the main entry points for the frontend and API clients.

5. Authentication is JWT-based. The `auth` routes handle registration and login, and authenticated requests likely gate access to employee and distribution operations. The presence of a `user` model and demo accounts in the docs suggests multi-user ownership and per-user data isolation.

6. The core domain model is expressed in `app/models/`. The main entities are:
   - `user` for authentication,
   - `employee` for restaurant staff,
   - `employee_day_off` for recurring availability rules,
   - `absence` for date-specific exceptions,
   - `distribution` for a generated tip payout run,
   - `distribution_entry` for the per-employee results within a distribution.
   These tables form the system’s persistent conceptual model.

7. The main business computation is isolated in `app/services/distribution_service.py`. This is the key domain boundary: it likely gathers employee data, excludes people based on day offs and absences, applies worked-hour or eligibility rules, and persists a distribution plus its entries.

8. The data flow for a distribution is important for architecture diagrams: a client calls the distributions endpoint, the route delegates to the service, the service reads employee/availability/absence data from the database, computes fair shares, then writes a `distribution` record and related `distribution_entry` rows.

9. Employee management is user-scoped and forms a second major flow. Managers create, update, list, and delete employees through the employee routes; the 2024-style migration names indicate ownership was later added to employees, so employees are tied back to a user account.

10. Availability management is split into two related subsystems: recurring `employee_day_off` records and one-off `absence` records. These are separate because day offs are standing rules while absences are date-range or date-based exceptions, and both influence distribution eligibility.

11. Database evolution is handled with Alembic under `migrations/`. The migration history shows the schema growing in stages: users, employees, employee day offs, distributions, distribution entries, absences, and later integrity/check constraints. That makes PostgreSQL the authoritative system of record.

12. The `docs/` directory is part of the architecture story even though it is not runtime code. It contains the OpenAPI spec, Bruno API collections, conceptual/logical models, and demo-account notes, which indicates the API is intended to be consumed and tested externally, with documentation as a first-class artifact.

13. The frontend is not in this repository, but the README shows it is a separate React/Vite app deployed on Railway and consuming this API. So the backend here should be treated as a standalone service with an external UI client and documented REST contract.

14. In diagram terms, the main boundaries are: client/UI → Flask routes → service/domain logic → SQLAlchemy models → PostgreSQL, with JWT auth crossing the request boundary and migrations/docs acting as supporting infrastructure around the core API.

Main entry points: [`app/__init__.py`](https://github.com/lemansachs29/fairtip-api/blob/main/app/__init__.py) (app package), [`migrations`](https://github.com/lemansachs29/fairtip-api/tree/main/migrations) (Migrations), [`app/services/distribution_service.py`](https://github.com/lemansachs29/fairtip-api/blob/main/app/services/distribution_service.py) (Distribution service), [`app/routes/employees.py`](https://github.com/lemansachs29/fairtip-api/blob/main/app/routes/employees.py) (Employee routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_runpy(("run.py<br/>entrypoint<br/>[run.py]"))
  node_appinit["app package<br/>flask app<br/>[__init__.py]"]
end

subgraph group_api["API Layer"]
  node_auth_routes["Auth routes<br/>jwt HTTP<br/>[auth.py]"]
  node_employee_routes["Employee routes<br/>resource HTTP<br/>[employees.py]"]
  node_absence_routes["Absence routes<br/>resource HTTP<br/>[absences.py]"]
  node_distribution_routes["Distribution routes<br/>resource HTTP<br/>[distributions.py]"]
end

subgraph group_domain["Domain"]
  node_distribution_service["Distribution service<br/>business logic"]
  node_user_model[("User<br/>auth model<br/>[user.py]")]
  node_employee_model[("Employee<br/>domain model<br/>[employee.py]")]
  node_dayoff_model[("Day off<br/>availability model")]
  node_absence_model[("Absence<br/>availability model<br/>[absence.py]")]
  node_distribution_model[("Distribution<br/>payout model<br/>[distribution.py]")]
  node_entry_model[("Entry<br/>payout model")]
end

subgraph group_infra["Infrastructure"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_extensions["Extensions<br/>flask infra<br/>[extensions.py]"]
  node_migrations["Migrations<br/>alembic"]
end

subgraph group_docs["Docs"]
  node_openapi["API spec<br/>contract docs<br/>[openapi.yaml]"]
  node_bruno["Bruno collections<br/>api docs"]
  node_models_docs["Model docs<br/>concept docs"]
end

node_runpy -->|"boots"| node_appinit
node_appinit -->|"loads"| node_config
node_appinit -->|"registers"| node_extensions
node_appinit -->|"mounts"| node_auth_routes
node_appinit -->|"mounts"| node_employee_routes
node_appinit -->|"mounts"| node_absence_routes
node_appinit -->|"mounts"| node_distribution_routes
node_auth_routes -->|"uses"| node_user_model
node_employee_routes -->|"uses"| node_employee_model
node_employee_routes -->|"scoped by"| node_user_model
node_absence_routes -->|"uses"| node_absence_model
node_absence_routes -->|"references"| node_employee_model
node_distribution_routes -->|"delegates"| node_distribution_service
node_distribution_service -->|"reads"| node_employee_model
node_distribution_service -->|"checks"| node_dayoff_model
node_distribution_service -->|"checks"| node_absence_model
node_distribution_service -->|"writes"| node_distribution_model
node_distribution_service -->|"writes"| node_entry_model
node_migrations -.->|"evolves"| node_user_model
node_migrations -.->|"evolves"| node_employee_model
node_migrations -.->|"evolves"| node_dayoff_model
node_migrations -.->|"evolves"| node_absence_model
node_migrations -.->|"evolves"| node_distribution_model
node_migrations -.->|"evolves"| node_entry_model
node_openapi -.->|"documents"| node_auth_routes
node_openapi -.->|"documents"| node_employee_routes
node_openapi -.->|"documents"| node_absence_routes
node_openapi -.->|"documents"| node_distribution_routes
node_bruno -.->|"tests"| node_auth_routes
node_bruno -.->|"tests"| node_employee_routes
node_bruno -.->|"tests"| node_absence_routes
node_bruno -.->|"tests"| node_distribution_routes
node_models_docs -.->|"explains"| node_employee_model
node_models_docs -.->|"explains"| node_distribution_model

click node_runpy "https://github.com/lemansachs29/fairtip-api/blob/main/run.py"
click node_appinit "https://github.com/lemansachs29/fairtip-api/blob/main/app/__init__.py"
click node_config "https://github.com/lemansachs29/fairtip-api/blob/main/app/config.py"
click node_extensions "https://github.com/lemansachs29/fairtip-api/blob/main/app/extensions.py"
click node_auth_routes "https://github.com/lemansachs29/fairtip-api/blob/main/app/routes/auth.py"
click node_employee_routes "https://github.com/lemansachs29/fairtip-api/blob/main/app/routes/employees.py"
click node_absence_routes "https://github.com/lemansachs29/fairtip-api/blob/main/app/routes/absences.py"
click node_distribution_routes "https://github.com/lemansachs29/fairtip-api/blob/main/app/routes/distributions.py"
click node_distribution_service "https://github.com/lemansachs29/fairtip-api/blob/main/app/services/distribution_service.py"
click node_user_model "https://github.com/lemansachs29/fairtip-api/blob/main/app/models/user.py"
click node_employee_model "https://github.com/lemansachs29/fairtip-api/blob/main/app/models/employee.py"
click node_dayoff_model "https://github.com/lemansachs29/fairtip-api/blob/main/app/models/employee_day_off.py"
click node_absence_model "https://github.com/lemansachs29/fairtip-api/blob/main/app/models/absence.py"
click node_distribution_model "https://github.com/lemansachs29/fairtip-api/blob/main/app/models/distribution.py"
click node_entry_model "https://github.com/lemansachs29/fairtip-api/blob/main/app/models/distribution_entry.py"
click node_migrations "https://github.com/lemansachs29/fairtip-api/tree/main/migrations"
click node_openapi "https://github.com/lemansachs29/fairtip-api/blob/main/docs/openapi.yaml"
click node_bruno "https://github.com/lemansachs29/fairtip-api/tree/main/docs/bruno/fairtip-api-collection"
click node_models_docs "https://github.com/lemansachs29/fairtip-api/blob/main/docs/conceptual-model.md"

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_runpy,node_appinit toneBlue
class node_auth_routes,node_employee_routes,node_absence_routes,node_distribution_routes toneAmber
class node_distribution_service,node_user_model,node_employee_model,node_dayoff_model,node_absence_model,node_distribution_model,node_entry_model toneMint
class node_config,node_extensions,node_migrations toneRose
class node_openapi,node_bruno,node_models_docs toneIndigo
```

## Components

### Runtime

Application boot and Flask wiring

- [run.py](https://github.com/lemansachs29/fairtip-api/blob/main/run.py): entrypoint · Starts the Flask application · `run.py`
- [app package](https://github.com/lemansachs29/fairtip-api/blob/main/app/__init__.py): flask app · Application factory and package bootstrap · `app/__init__.py`

### API Layer

HTTP routes by resource

- [Auth routes](https://github.com/lemansachs29/fairtip-api/blob/main/app/routes/auth.py): jwt HTTP · Registration and login endpoints · `app/routes/auth.py`
- [Employee routes](https://github.com/lemansachs29/fairtip-api/blob/main/app/routes/employees.py): resource HTTP · CRUD for user-scoped employees · `app/routes/employees.py`
- [Absence routes](https://github.com/lemansachs29/fairtip-api/blob/main/app/routes/absences.py): resource HTTP · Endpoints for employee absences · `app/routes/absences.py`
- [Distribution routes](https://github.com/lemansachs29/fairtip-api/blob/main/app/routes/distributions.py): resource HTTP · Endpoints for tip distribution runs · `app/routes/distributions.py`

### Domain

Core models and business services

- [Distribution service](https://github.com/lemansachs29/fairtip-api/blob/main/app/services/distribution_service.py): business logic · Computes fair tip shares and persists results · `app/services/distribution_service.py`
- [User](https://github.com/lemansachs29/fairtip-api/blob/main/app/models/user.py): auth model · Accounts and ownership boundary · `app/models/user.py`
- [Employee](https://github.com/lemansachs29/fairtip-api/blob/main/app/models/employee.py): domain model · Restaurant staff owned by a user · `app/models/employee.py`
- [Day off](https://github.com/lemansachs29/fairtip-api/blob/main/app/models/employee_day_off.py): availability model · Recurring availability rule · `app/models/employee_day_off.py`
- [Absence](https://github.com/lemansachs29/fairtip-api/blob/main/app/models/absence.py): availability model · Date-based exception to availability · `app/models/absence.py`
- [Distribution](https://github.com/lemansachs29/fairtip-api/blob/main/app/models/distribution.py): payout model · A generated tip distribution run · `app/models/distribution.py`
- [Entry](https://github.com/lemansachs29/fairtip-api/blob/main/app/models/distribution_entry.py): payout model · Per-employee distribution result · `app/models/distribution_entry.py`

### Infrastructure

Settings, extensions, database migrations

- [Config](https://github.com/lemansachs29/fairtip-api/blob/main/app/config.py): settings · Environment-driven application configuration · `app/config.py`
- [Extensions](https://github.com/lemansachs29/fairtip-api/blob/main/app/extensions.py): flask infra · Shared Flask extensions and database/auth wiring · `app/extensions.py`
- [Migrations](https://github.com/lemansachs29/fairtip-api/tree/main/migrations): alembic · Schema evolution for PostgreSQL · `migrations`

### Docs

API and model documentation

- [API spec](https://github.com/lemansachs29/fairtip-api/blob/main/docs/openapi.yaml): contract docs · OpenAPI contract for external clients · `docs/openapi.yaml`
- [Bruno collections](https://github.com/lemansachs29/fairtip-api/tree/main/docs/bruno/fairtip-api-collection): api docs · Executable request collections for the API · `docs/bruno/fairtip-api-collection`
- [Model docs](https://github.com/lemansachs29/fairtip-api/blob/main/docs/conceptual-model.md): concept docs · Conceptual and logical data model notes · `docs/conceptual-model.md`

## Connections

- run.py → app package: boots · Entry point starts the Flask app
- app package → Config: loads · App initialization reads settings
- app package → Extensions: registers · App wires shared extensions
- app package → Auth routes: mounts · Application exposes auth endpoints
- app package → Employee routes: mounts · Application exposes employee endpoints
- app package → Absence routes: mounts · Application exposes absence endpoints
- app package → Distribution routes: mounts · Application exposes distribution endpoints
- Auth routes → User: uses · Registration and login operate on users
- Employee routes → Employee: uses · Employee CRUD persists employee records
- Employee routes → User: scoped by · Employee data is owned per user
- Absence routes → Absence: uses · Absence endpoints manage absence records
- Absence routes → Employee: references · Absences belong to employees
- Distribution routes → Distribution service: delegates · Routes hand computation to the service layer
- Distribution service → Employee: reads · Service gathers eligible employees
- Distribution service → Day off: checks · Recurring day offs affect eligibility
- Distribution service → Absence: checks · Absences affect eligibility
- Distribution service → Distribution: writes · Service persists each distribution run
- Distribution service → Entry: writes · Service persists per-employee entries
- Migrations → User: evolves · Database schema grows around user ownership
- Migrations → Employee: evolves · Migrations create and refine employee schema
- Migrations → Day off: evolves · Migrations add recurring day-off rules
- Migrations → Absence: evolves · Migrations add absences
- Migrations → Distribution: evolves · Migrations add distribution runs
- Migrations → Entry: evolves · Migrations add distribution entries
- API spec → Auth routes: documents · OpenAPI describes auth endpoints
- API spec → Employee routes: documents · OpenAPI describes employee endpoints
- API spec → Absence routes: documents · OpenAPI describes absence endpoints
- API spec → Distribution routes: documents · OpenAPI describes distribution endpoints
- Bruno collections → Auth routes: tests · Bruno collections exercise the auth API
- Bruno collections → Employee routes: tests · Bruno collections exercise employee flows
- Bruno collections → Absence routes: tests · Bruno collections exercise absence flows
- Bruno collections → Distribution routes: tests · Bruno collections exercise distribution flows
- Model docs → Employee: explains · Conceptual model documents key entities
- Model docs → Distribution: explains · Conceptual model documents payout structure
