How lemansachs29/fairtip-api works
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: __init__.py app package · migrations Migrations · distribution_service.py Distribution service · employees.py Employee routes
Components 19
Runtime
Application boot and Flask wiring
- run.py · Starts the Flask application
run.py - app package · Application factory and package bootstrap
app/__init__.py
API Layer
HTTP routes by resource
- Auth routes · Registration and login endpoints
app/routes/auth.py - Employee routes · CRUD for user-scoped employees
app/routes/employees.py - Absence routes · Endpoints for employee absences
app/routes/absences.py - Distribution routes · Endpoints for tip distribution runs
app/routes/distributions.py
Domain
Core models and business services
- Distribution service · Computes fair tip shares and persists results
app/services/distribution_service.py - User · Accounts and ownership boundary
app/models/user.py - Employee · Restaurant staff owned by a user
app/models/employee.py - Day off · Recurring availability rule
app/models/employee_day_off.py - Absence · Date-based exception to availability
app/models/absence.py - Distribution · A generated tip distribution run
app/models/distribution.py - Entry · Per-employee distribution result
app/models/distribution_entry.py
Infrastructure
Settings, extensions, database migrations
- Config · Environment-driven application configuration
app/config.py - Extensions · Shared Flask extensions and database/auth wiring
app/extensions.py - Migrations · Schema evolution for PostgreSQL
migrations
Docs
API and model documentation
- API spec · OpenAPI contract for external clients
docs/openapi.yaml - Bruno collections · Executable request collections for the API
docs/bruno/fairtip-api-collection - Model docs · Conceptual and logical data model notes
docs/conceptual-model.md
Connections 34
- 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