Home

OcotilloAPI Internal Wiki

Welcome to the internal engineering documentation hub for OcotilloAPI. This wiki is grounded in the actual codebase and is explicit about where team process is fully codified versus where it still needs confirmation.

Core Tech Stack

Layer	Technology
Language	Python 3.13+
Framework	FastAPI / Starlette
Package Manager	uv
Database	PostgreSQL + PostGIS (WGS84 / SRID 4326)
ORM	SQLAlchemy 2.0 + GeoAlchemy2
Migrations	Alembic
Auth	Authentik (OAuth2 / OIDC)
OGC API	pygeoapi

---

Section Map

Getting Started

• Getting Started — local setup, dependencies, first-run instructions

Technical Documentation

• Architecture Overview — runtime assembly, middleware, database and spatial stack
• API Schemas and Auth — routers, schema conventions, role-based auth, OpenAPI surfaces
• Data Model Overview — domain hierarchy, supporting models, legacy NMA models, ERD
• Legacy Transfer Pipeline — NM_Aquifer migration orchestration, environment toggles, performance guidance
• CSV Ingestion and Validation — well inventory and groundwater level bulk import flows

Process & Workflow Guides

• Deployment and Operations — CI/CD pipeline, App Engine hosting, pygeoapi ops, observability, troubleshooting
• Testing and Quality — test layout, BDD, CI jobs, formatting and linting

Development Standards

• Development Standards — branching, PR requirements, coding conventions, schema patterns
• Development Workflow — day-to-day feature loop, model changes, data migrations

---

Important Repo Drift To Know Up Front

• pyproject.toml requires Python >=3.13. README.md still says Python 3.11+.
• The live app entrypoint is main:app. README.md still references uvicorn app.main:app --reload.
• .env.example does not list every variable used by the codebase. Admin, pygeoapi, telemetry, and Cloud SQL settings are only discoverable from source.
• The repo has no CONTRIBUTING.md, PR template, or CODEOWNERS. Branch naming and PR expectations are only partially inferable from GitHub Actions.

Suggested Next Steps

• Confirm branch naming and PR review requirements with the team and update Development Standards.
• Add a CONTRIBUTING.md or PR template to codify expectations in the repo itself.
• Add owners for the major areas in this wiki so operational knowledge is not implicit.
• Decide whether README drift should be fixed in-repo or treated as intentional wiki-only clarifications.