A backend platform for infrastructure cost intelligence and bid-item analysis. Built with FastAPI, SQLAlchemy, and PostgreSQL, Cost Query Pro is designed to query, clean, and analyze construction cost data at scale — empowering engineers, estimators, and project managers with smarter insights.
| Branch | Build Status | Python | Framework | License | Project Status |
|---|---|---|---|---|---|
| main |  |
 |
 |
 |
 |
| dev |  |
|
|
|
|
Version: v0.1.0 Status: Early Release (MVP)
| Layer | Technology |
|---|---|
| Framework | FastAPI |
| Database | PostgreSQL + SQLAlchemy ORM |
| Auth | JWT-based authentication |
| Migrations | Alembic |
| Testing | Pytest |
| Package Manager / Env | uv |
| Deployment | Docker / AWS RDS (planned) |
| Language | Python 3.12 |
- 🔐 Secure authentication with JWT
- 🧮 Project, item, and cost model endpoints
- 🧹 Automated purge routines for old or duplicate data
- 🧱 Database migrations and ORM models
- 🧰 Modular architecture with dedicated folders for logic, schemas, and services
- 🧾 Built-in API documentation via Swagger UI (
/docs)
git clone https://github.com/Brice-Backend-Projects/Cost-Query-Pro.git
cd Cost-Query-Prouv venv
source .venv/bin/activate # (Windows: .venv\Scripts\activate)uv syncensure the following environment variables are set:
export PYTHONPATH=$PWD/srcthen run the app:
uvicorn cost_query_pro.main:app --reloadVisit http://localhost:8000/docs
cost_query_pro/
│
├── app/ # Main application code
│ ├── __init__.py
│ ├── main.py # FastAPI app entry point
│ ├── models/ # SQLAlchemy models
│ │ └── __init__.py
│ ├── db/ # Database config and session utilities
│ │ └── __init__.py
│ ├── api/ # API route definitions
│ │ ├── __init__.py
│ │ ├── auth.py
│ │ ├── projects.py
│ │ ├── items.py
│ │ └── purge.py
│ ├── config/ # Configuration files
│ │ ├── __init__.py # initialization file
│ │ └── settings.py # settings file
│ ├── core/ # Core logic/utilities (e.g. purge scripts)
│ │ ├── __init__.py
│ │ ├── security.py
│ │ └── data_upload.py
│ ├── schemas/ # Pydantic schemas for API validation
│ │ └── __init__.py
│ ├── templates/ # HTML templates (if using Jinja2)
│ │ └── ...
│ ├── static/ # CSS, JS, images (if applicable)
│ │ └── ...
│ └── services/ # Business logic services
│ └── __init__.py
│
├── migrations/ # DB migrations (e.g. Alembic)
│
├── tests/ # Unit and integration tests
│ ├── __init__.py
│ ├── test_projects.py
│ ├── test_items.py
│ └── test_auth.py
│
├── .env # Environment variables (never commit secrets!)
├── .gitignore
├── uv.lock # Locked dependencies managed by uv
├── README.md
├── LICENSE
└── pyproject.toml # Project metadata and dependency declarations- How to architect a production-ready FastAPI backend with modular separation (api, core, db, schemas, services)
- Managing SQLAlchemy sessions and transactions safely across async endpoints
- The importance of type-safe validation with Pydantic models for clean data ingestion
- Implementing JWT authentication and secure password hashing workflows
- Building and maintaining database migrations with Alembic
- Designing for maintainability — breaking logic into reusable service layers
- Leveraging uv for faster dependency installs, reproducible environments, and isolated builds
- Writing meaningful tests to prevent regressions during refactors
- Building with deployment in mind (directory structure, .env separation, and Docker-readiness)
- Documenting the architecture so others (or future me) can onboard easily
- 🔑 Role-based access control (RBAC): differentiate between admin, project manager, and analyst users
- 🧾 Bid-item cost analytics: integrate real municipal datasets to benchmark infrastructure costs
- 💾 Caching layer: add Redis or SQLite caching for faster repeat queries
- 📊 Reporting tools: export project summaries to PDF and Excel
- ⚙️ Background tasks: schedule cost refreshes or purge routines asynchronously
- ☁️ Cloud deployment: Dockerize and deploy to AWS App Runner with RDS Postgres backend
- 🤖 Machine learning integration: train models to detect anomalies or pricing trends across regions
- 🧰 API Gateway Integration: expose authenticated endpoints for external engineering dashboards
- FastAPI application structure implemented
- Core endpoints for project and cost queries
- SQLAlchemy ORM models created
- Alembic migrations enabled
- JWT authentication (access + refresh)
- Modular routing with dependency injection
- Basic schema validation
- CI/CD pipeline fully configured (GitHub Actions)
- Local development environment configured
- Early testing with internal datasets
- Security remediation: pinned
pyasn1>=0.6.2to address Dependabot-reported DoS risk inv0.6.1BER decoding
- Production configuration profiles
- PostgreSQL / AWS RDS integration
- Gunicorn/Uvicorn production server setup
- Security headers, CORS configuration, rate limiting
- Logging & error-handling improvements
- Environment-based settings cleanup
- Expanded project type taxonomy
- Advanced querying features
- Pagination & filtering
- Enhanced input validation
- Robust exception handling
- Performance profiling & endpoint optimization
- Caching layer (Redis) for high-traffic endpoints
- Admin dashboard endpoints
- Role-based permissions (admin, analyst, standard)
- API key generation for internal services
- Audit logging for sensitive operations
- Export cost data (CSV/JSON)
- Webhook support for events
- REST-to-REST integration examples
- Optional ETL pipelines for external civil engineering datasets
- Final migration to fully modular src/ layout
- Clear separation of:
routers/services/repositories/schemas/core/
- Full end-to-end test suite (pytest)
- Type-hint and docstring coverage improvements
- Performance tuning
- Documentation overhaul (OpenAPI + Markdown)
This project is open source under the MIT License — free to use, modify, and distribute.
Author: Brice A. Nelson
🌐 devbybrice.com
💼 LinkedIn
“Precision in cost, clarity in data — because every number tells a story.” 🧾