naina-sriv/ftp

1. Overall shape

This is a single FastAPI backend for civic issue reporting. It is organized as a layered monolith: HTTP routers at the edge, service-like auth/dependency helpers in app/core, SQLAlchemy ORM models in app/models, and Pydantic schemas in app/schema.

2. Request entrypoint

app/main.py is the application bootstrap. It creates the FastAPI app and wires in the route modules under app/routers, so all client traffic enters through one API process.

3. API boundary

The functional API is split by concern:

- auth.py for registration and login

- issue.py for issue CRUD

- comments.py for issue comments

- votes.py for voting and escalation logic

This separation is important for diagramming because each router maps to a distinct user action and resource type.

4. Identity and access control

Authentication is JWT-based, backed by password hashing in app/core/security.py. The get_current_user dependency in app/core/dependencies.py is the main enforcement point for protected routes. The README indicates the token also carries constituency information, which scopes what each user can see and modify.

5. Domain model and persistence

The database layer centers on five core entities in app/models: User, Constituency, Issue, Comment, and Vote. These form the persistent domain graph:

- users belong to a constituency

- issues are reported within a constituency

- comments attach to issues

- votes attach to issues and are used for threshold validation

6. Data validation layer

app/schema contains the Pydantic request/response contracts for each domain object, plus token schemas. This is the boundary between external JSON and internal ORM objects, and it is where API payload shape and response serialization are enforced.

7. Database infrastructure

app/db.py is the database/session boundary. The repository is designed to run against PostgreSQL in normal use, but the tests use SQLite. This makes the persistence layer portable while keeping local and test execution lightweight.

8. Issue lifecycle and escalation

The key business rule is threshold-based escalation. Issues start as open; when enough unique users vote, the issue transitions to escalated and a threshold flag is set. The vote endpoint triggers this check asynchronously via FastAPI BackgroundTasks, so the API response returns immediately while the status update happens after the write.

9. Constituency scoping as a system-wide constraint

Constituency is not just metadata; it is a hard access boundary. Reads and writes for issues, comments, and votes are constrained to the user’s constituency, which prevents cross-constituency interaction and keeps the data model aligned with the product goal.

10. Testing architecture

tests/conftest.py provides an in-memory SQLite fixture, and tests/test_routes.py exercises the API end-to-end. The tests cover auth, CRUD, comment flows, voting rules, duplicate vote prevention, and threshold escalation, so the test suite validates the full request-to-database path rather than isolated units.

11. Configuration and runtime inputs

app/core/config.py centralizes environment-driven settings such as database URL, secret key, signing algorithm, and token expiry. That makes runtime behavior configurable without changing application code, which is important for diagramming deployment dependencies.

12. External-facing interfaces

The only externally visible interface is the HTTP API. There are no queues, caches, or separate worker services in the current implementation; async behavior is handled in-process with FastAPI background tasks, and persistence is the database.

13. Practical architecture summary

The clearest diagram is: client → FastAPI routers → auth/dependency layer → ORM/models → SQLAlchemy session/database, with background tasks branching off from voting to perform escalation checks. The main cross-cutting concerns are JWT auth, constituency scoping, and schema validation.