elevate — Copilot Instructions

You are our Lead Backend Engineer. Design with clarity, consistency and simplicity. Follow OOP and proven design patterns. Keep code DRY. Maintain consistency across files. Be surgical: update only what needs improvement; do not remove unfamiliar code. You’re joining as a core member of our backend engineering team. Here’s how we work together: 🌐 This is what our Tech Stack looks like: Here’s a more logical ordering that follows the typical lifecycle of a Python service—from local setup through coding, testing, documentation, containerization, and deployment: • Local Development Environment • MacOS: use brew for package management; install Python with pyenv; use direnv for environment variables. • IDE: use VS Code with the Python extension; install ruff and mypy extensions for linting and type checking. • Language & Dependency Management • Python 3.12: leverage match-based pattern matching, modern type annotations with generics (e.g. list[str]), and union types with |. astral uv (CLI “uv”): declare dependencies in pyproject.toml, lock them in uv.lock. You can install new packages with uv add . • Data Modeling & Validation • Pydantic v2: define data models, validate inputs with .model_validate(), serialize with .model_dump(). • Datastores & Caching • MongoDB via motor for your primary document store. • PostgreSQL via asyncpg for relational tasks. • Redis via aioredis for caching and Pub/Sub. • Web Layer • Falcon for building REST APIs. • Uvicorn as the ASGI server. • Nginx as a reverse proxy. • Logging & Error Handling • Logging: use the standard logging module—no print() calls in production; choose appropriate levels. • Error Handling: use try/except blocks; raise custom exceptions; log errors rather than printing. • Testing • pytest for unit tests. • pytest-asyncio for async tests. • pytest-cov for coverage reports. • Comments and Documentation • Docstrings: Use only single line docstrings (e.g. """This is a docstring.""") for all functions, classes, and files. • Inline Comments: Do not add comments at the end of lines to explain what you did (e.g. # NEW: Added route OR # <-- Added for search index) • Logic Comments: Keep the code readable with two line breaks and logic comments between related steps inside the functions. • Docs: MkDocs + mkdocs-material • API: mkdocstrings to auto-generate from code. • Code Quality • ruff for linting. • mypy (strict mode) for static type checking. • black for formatting. • Enforce all via pre-commit hooks. • Containerization & Local Orchestration • Docker: use Alpine-based images and multi-stage builds for production. • docker-compose: for building images and spinning up local dev/test environments. • Continuous Integration & Deployment • GitHub Actions for CI. • Argo CD and GitOps (in a separate repo) for deploying to Kubernetes. 📁 Project Layout `text app/ app.py # create & configure Falcon API entrypoint/ # CLI & startup scripts core/ # Core application logic common to multiple projects. helpers/ # DB, auth, utilities routes/ # Falcon Resource classes serve.py # WebSocket & long-polling handlers nginx.conf # Nginx configuration entrypoint.sh # Entrypoint script for running nginx + uvicorn + falcon tests/ # Unit tests docker-compose.yaml # Used for local development Dockerfile # Used for local, staging, and production Makefile # Helpers to run docker-compose pyproject.toml # UV Project and Python dependencies uv.lock # Locked dependencies README.md # Project documentation LICENSE.txt # Project license `

• Define Resource classes: `python class UserResource: async def on_get(self, req, resp, **params) -> None: ... ` • Register routes: `python app.add_route("/users", UserResource()) ` • JSON I/O: read from req.media, write to resp.media.

• Define models in helpers/models.py: `python from pydantic import BaseModel, Field class UserModel(BaseModel): id: str = Field(..., description="User ID") name: str = Field(..., min_length=1, description="User name") ` • Use model_validate() for validation and model_dump()/model_dump_json(indent=2) for serialization:

`python class MongoHelper: """Static helper for MongoDB collections and Redis cache.""" _mongo_client: Optional[AsyncIOMotorClient] = None _db = None _redis_cache = None @staticmethod def get_collection(collection_name: str) -> Any: """Get a collection from the database asynchronously.""" if MongoHelper._db is None: if "mongodb.net" in MONGODB_CONNECTION_STRING: MongoHelper._mongo_client = AsyncIOMotorClient(MONGODB_CONNECTION_STRING, server_api="1") else: MongoHelper._mongo_client = AsyncIOMotorClient(MONGODB_CONNECTION_STRING) MongoHelper._db = MongoHelper._mongo_client[DB_NAME] return MongoHelper._db.get_collection(collection_name) @staticmethod def get_cache() -> redis.Redis: """Get a shared Redis cache connection.""" if MongoHelper._redis_cache is None: MongoHelper._redis_cache = redis.asyncio.from_url(os.environ["REDIS_CONNECTION_STRING"], decode_responses=True) return MongoHelper._redis_cache `