Beginner Capstone: Build and Prove a Ticket API

Build the first complete SupportDesk AI backend without AI. This is deliberate: durable data, clear contracts, authorization boundaries, testing, migrations, and operations are the foundation AI features depend on. You will deliver a containerized FastAPI ticket service and an evidence package that proves its behavior from a clean checkout.

What will you be able to demonstrate?

• create, read, list, update, and resolve tickets;
• validate inputs and publish a reviewed OpenAPI contract;
• persist through PostgreSQL with Alembic migrations;
• test domain, HTTP, and real database behavior;
• build and run a non-root container reproducibly.

What are the required user stories?

1. A caller creates a ticket with subject, body, and priority.
2. A caller reads one ticket by UUID.
3. A caller lists tickets with stable cursor pagination and limit 1..100.
4. A caller changes subject or priority using optimistic version control.
5. A caller resolves an open ticket; resolving it twice returns a stable conflict.
6. An operator checks liveness and readiness.

For this capstone, use a fixed development principal and organization injected through a dependency. Clearly label it as a learning substitute for authentication—not a production identity system. Every repository method still receives organization_id so tenancy cannot be retrofitted accidentally.

What must the architecture contain?

Required artifacts:

• pyproject.toml, lockfile, README, .env.example, .gitignore;
• domain ticket and transition rules;
• separate create, patch, and public-view schemas;
• repository protocol, SQLAlchemy adapter, unit of work;
• Alembic fresh-install migration;
• FastAPI app, problem responses, request correlation;
• Dockerfile and local compose file for PostgreSQL;
• unit, API, and PostgreSQL integration tests;
• exported OpenAPI document and a short architecture decision record.

What acceptance tests must pass?

How should you verify it?

From a clean checkout:

Run the image, execute a scripted curl journey, restart it, and repeat the read. Preserve command output, test report, OpenAPI diff, and container user evidence.

What should not be added?

Do not add Redis, a queue, Kubernetes, a model provider, a generic repository framework, or microservices. Every omitted technology is an intentional complexity decision.

AI Pair-Programmer Prompt

Rubric

Pass: at least 80%, with no failure in tenant isolation, persistence, or secret handling.

Knowledge check

1. Why is AI intentionally excluded?
2. What proves persistence?
3. Why keep tenant scope even with a fixed development principal?

---

Answers

1. To prove the deterministic backend foundation before adding probabilistic complexity.
2. Committed data survives process/container restart and is read from PostgreSQL.
3. It makes isolation a foundational invariant and enables meaningful negative tests.

Completion checklist

• Clean-checkout verification passes.
• All mandatory negative tests pass.
• Evidence package and ADR are complete.
• No unnecessary infrastructure was added.

Primary references

• FastAPI documentation
• SQLAlchemy documentation
• Alembic documentation