calibration-service

Pre-requisites

• Python 3.12 or higher, link
• uv for python runtime and dependency management, link
• Docker Desktop or Docker Compose capable tool (e.g. podman desktop or rancher desktop)
• Node.js for Pyright pre-commit hook execution, link

Quick Start

A) Online Deployment

• Live Docs - GitHub pages hosted docs site making reading these docs a bit easier
• Live Site - deployed application # TODO: (future)

(B) Offline Deployment Options

Prepare

Download source:

• Clone the repository, and go into the project directory calibration-service

Avoid port conflicts:

• 5777 - port of dev db
• 5778 - port of test db
• 8777 - port of FastAPI web driver

Troubleshooting: Verify if a local service is listening by run lsof -i :<port> to see binding. If found, pkill -9 <PID> to stop

Containerized Deployment

1. Start Docker Desktop
2. Run Docker compose: pull images, builds, runs migrations, seeds and starts the container

   docker compose up

3. Go to localhost:8777/docs - OpenAPI spec to explore the api
4. (Optional) Open online documentation

Note: for local deployment see DEVELOPER

Cleanup

docker compose down -v --rmi local

Points of Interest

• OpenApi Specification
• Calibration Repository (Postgres)
• Tag Repository (Postgres)
• Calibration Routes (FastAPI)
• Tag Routes (FastAPI)
• Calibration Api integration tests
• Tagging Api integration tests

Testing and validating system functionality

End to End

With the project up and running use docker cli to execute the e2e tests in a different terminal

• test_api_use_cases_e2e.py take home assignment uc1-4 tests

• test_tag_archiving_e2e.py take home assignment uc5

  docker compose exec web uv run test_e2e

Component Integration

docker compose exec web uv run pytest tests/integration/drivers/rest

docker compose exec web uv run pytest tests/integration/repositories

Unit

docker compose exec web uv run test

ERD

Next Steps

Where I would want to continue to refine the system.

• Users: a users table to replace the "username" on a CalibrationAssociation, and allow for something to bring a trackable Actor into the system
• ISessions: bring Session up into the Entity layer and removing the third-party reliance on SqlAlchemy's AsyncSession
• IAuthentication Service: that encapsulates sign_up, sign_in, and sign_out use cases and helps demonstrate how easy swapping out one oidc provider for another could be
• Instrumentation/Monitoring: wrappers to monitor and benchmark each system interaction as it goes through the boundaries of the Clean Architecture surrounds all

Inspiration

I’ve been eager to try Clean Architecture, so I was excited to take this project as a chance to dive in outside of work. In day-to-day development, we often have to stay laser-focused on shipping just enough—so it was refreshing to explore a more intentional, scalable structure. I started by defining the use case and interfaces, then adapted a MongoDB repository based on shaliamekh, and later swapped in a PostgreSQL version without touching the core logic. That flexibility—being able to change out infrastructure without rewriting business rules—really drove home the value of this approach. Clean Architecture made it easy to innovate at the edges while keeping the core rock-solid. If you’re curious about the structure, I nerded out a bit more in the ARCHITECTURE section.

Developer Experience

Coming from a Node.js and TypeScript background, I was initially skeptical about Python—especially around tooling, type safety, and developer ergonomics. But this project turned out to be a crash course in how far the Python ecosystem has come. Tools like uv and pyproject.toml gave me the dependency management experience I’d been missing, and enabling Pyright in PyCharm brought back the type hints, squiggles, and Intellisense I rely on daily. Once dialed in, my Python dev environment felt just as powerful—if not more streamlined—than my usual setup.

On the infrastructure side, working with Terraform reminded me how much I enjoy bridging systems design with application code—something I previously explored through AWS CDK. This project showed me that clean architecture, code organization, and system-level thinking (along with solid tooling habits) are transferable across languages. And in the age of AI, where every developer effectively has a supercomputer at their side, the ability to learn quickly and structure ideas well has never been more important. It’s not just about syntax—it’s about creating an environment that helps you think clearly and ship confidently.

Additional Documentation

• Developer Guide - Day-to-day development workflows
• Database Management - Detailed information about database management operations
• Architecture Inspiration - System design and software architecture inspiration
• Testing Approach - How to execute project tests and the packages used
• CI/CD - Description of CI/CD workflows

License

[License details here]