Document Scope
The Python backend is moving from a loose script collection toward a structured, package-based, testable backend system. This requires a standard tooling layer for dependency management, project metadata, script execution, code formatting, linting, testing, validation, CI/CD pipeline automation, and future database migrations.
This document defines the backend tooling and quality standard. It explains the role of the selected Python project manager, linting and formatting layer, testing layer, model layer, configuration layer, database access layer, schema migration layer, and remote repository CI/CD pipeline layer.
This document is written for human developers, ChatGPT sessions, Codex sessions, AI-assisted development tools, future AI agents, and automation workers. It is intended to guide tool use before implementation tasks begin.
1. Purpose
The purpose of this document is to standardize the Python backend toolchain.
Without a standard toolchain, each future script or AI-generated change may introduce a different dependency pattern, formatting style, test structure, environment setup, or execution method. That would make the project harder to maintain as it grows.
The backend needs a consistent foundation before major restructuring continues. This document defines that foundation.
Backend tooling expectations also depend on repository class. A deployable application repository needs stronger validation and release awareness than a context/reference repository. A utility repository that can delete, archive, upload, or restore files may require stronger safeguards than its small size suggests. Classify the repository before changing backend tooling.
2. Tool Definitions
| Generic layer term | Current selected implementation | Role |
|---|---|---|
| Python project manager | uv |
Dependencies, virtual environments, lockfiles, Python versions, script execution |
| linting and formatting layer | Ruff | Formatting, import organization, lint checks, style consistency |
| testing layer | pytest | Unit tests, integration tests, regression tests, safety tests |
| model layer | Pydantic | Data validation and structured internal/API models |
| configuration layer | Pydantic Settings | Environment-aware settings and validated configuration |
| database access layer | SQLAlchemy Core | Standard query execution and database access pattern |
| schema migration layer | Alembic where compatible | Version-controlled database schema changes |
| terminal output layer | Rich | Readable CLI output and diagnostic summaries |
| Python HTTP client layer | HTTPX | New Python HTTP integrations where appropriate |
| remote repository CI/CD pipeline service | GitLab CI/CD currently | Remote validation, test, build, package, and deployment automation |
| pipeline configuration | .gitlab-ci.yml currently |
Repository-specific CI/CD job and stage definition |
Use the generic layer terms throughout architecture documents. Use the selected implementation names when writing setup guides, configuration examples, or implementation-specific standards.
3. Python Project Manager Standard
The Python project manager is the foundation for backend dependency management and script execution.
It should manage project metadata, runtime dependencies, development dependencies, virtual environments, lockfiles, Python version expectations, and script execution.
The backend should avoid global package installation instructions unless they are explicitly marked as machine setup prerequisites. Project dependencies should be declared through project metadata and installed through the project manager.
The goal is reproducible setup. A future AI session should be able to inspect the project metadata and understand which dependencies are official.
4. Dependency Standard
Dependencies should be minimal and justified.
Before adding a dependency, answer whether the selected stack already includes a tool for this, whether the dependency is mature and maintained, whether it works on Windows now and Linux later, whether it complicates deployment, whether it overlaps with another selected layer, whether it is runtime or development-only, and whether it creates security, licensing, or maintenance concerns.
Do not add frameworks merely because they are popular.
Development-only tools should be separated from runtime dependencies where the project manager supports that distinction.
4.1 Supply Chain Requirement for Backend Dependencies
Backend dependencies are external artifacts. They are governed by the Supply Chain Security Standard before they are added, upgraded, downgraded, replaced, removed, or moved between dependency groups.
Before adding a backend dependency, the AI must identify the operational need, review whether the approved stack already solves the problem, verify the official source, verify publisher and repository control, identify the license, select an appropriate stable version, record hash or lockfile evidence where supported, evaluate security history, and obtain operator approval. A package may be architecturally aligned with the selected stack and still require artifact-level approval.
Dependency changes must update the appropriate project metadata and lockfile together. A dependency change that lacks lockfile evidence, record updates, or operator approval is not ready for commit.
5. Linting and Formatting Standard
The linting and formatting layer should enforce consistent Python style.
This matters because multiple AI systems may edit the codebase over time. Without automated standards, the repository will accumulate inconsistent imports, formatting, naming, and common mistakes.
Adoption should be incremental. The project should avoid a giant formatting commit that obscures meaningful code changes unless that commit is intentionally scoped as formatting-only.
A good adoption pattern is to configure the tool, run it in check mode, review findings, fix high-confidence issues, commit formatting separately when needed, and tighten rules gradually.
6. Testing Standard
The testing layer should protect critical behavior before broad refactoring.
The first tests should focus on high-risk areas: configuration loading, environment separation, database adapter behavior, database query helpers, Telegram publishing safety, deduplication, operations incident creation, remediation jobs, API response models, and service-layer workflows.
Do not wait for perfect full coverage before writing tests. Critical-path tests are more valuable than broad low-value coverage.
AI-generated code that changes core behavior should include or update tests where practical.
7. Model and Configuration Standard
The model layer should define structured data where it reduces ambiguity.
The configuration layer should centralize environment-specific settings.
Together, these layers should reduce loose dictionaries, scattered environment parsing, unvalidated settings, and unclear data contracts.
Use models where data crosses boundaries. Use validated settings where runtime behavior depends on environment, database, provider, or feature configuration.
Do not rewrite every structure immediately. Introduce models and settings where they support active refactoring or new APIs.
8. Database Tooling Standard
The database access layer should standardize how Python code works with structured databases.
The schema migration layer should manage controlled database schema changes where compatible with the selected database path.
Do not begin with a broad migration. Start by identifying the current adapter behavior, current database call sites, current schema management practices, and current staging/production separation.
The database tooling migration should be staged: inventory current database access patterns, define the standard helper layer, preserve existing SQL where useful, centralize connection and execution behavior, add logging and timing, add tests, and introduce schema migrations for future changes where compatible.
9. Script Execution Standard
New Python scripts should be runnable through the project manager once the project manager is adopted.
Scripts should be thin entry points that call shared modules. They should not become isolated applications with their own dependency assumptions.
A script should identify purpose, environment, whether it can write data, whether it can touch production, validation behavior, output format, and exit behavior.
Scripts that can mutate production data require stronger safeguards than read-only diagnostics.
10. CI/CD Tooling and Quality Standard
The remote repository CI/CD pipeline service is part of backend tooling quality.
Backend tooling changes should consider whether the pipeline must be created or updated. This includes changes to:
project manager configuration,
dependency files,
lockfiles,
Python version files,
linting configuration,
formatting configuration,
test commands,
package layout,
script entry points,
runtime commands,
database migration commands,
build commands,
deployment commands,
environment variables,
secrets or protected variable references.
The first pipeline for a backend repository should normally be validation-only. It may run compile checks, lint checks, formatting checks, tests, import checks, or other no-mutation validation. Deployment should not be added casually.
Pipeline jobs should use the same approved commands documented for the repository. If local validation uses the approved Python runner, the pipeline should use the corresponding repository-safe command after the project manager has been adopted.
Pipeline configuration changes are high-impact. They can run commands, consume secrets, publish artifacts, deploy services, or mutate environments. AI-assisted work must not change pipeline configuration unless the task explicitly permits it.
Before commit readiness, backend tooling work must include a pipeline impact review. The review should say whether the pipeline file changed, whether a pipeline update is needed, what pipeline behavior is expected after push, and whether any deployment job is expected.
11. Validation Before Commit
Before committing backend tooling or restructuring changes, validation should match the risk.
For import-path changes, run compile checks and import checks.
For database-facing changes, run database-specific validation and no-mutation checks where possible.
For API changes, validate request and response models and tests.
For tooling changes, run the tool in check mode before applying broad fixes.
For repository changes, review CI/CD pipeline impact before recommending a commit. If the repository has a pipeline, identify whether the changed tooling, commands, dependencies, tests, or runtime behavior require a pipeline update.
A future task should state validation before implementation begins.
Architectural Impact Review Requirement
Before any repository commit is treated as ready, the session must perform an Architectural Impact Review. This review is broader than CI/CD. It asks whether the work affected or exposed required changes to validation, dependencies, configuration, environment variables, runtime commands, database behavior, API contracts, frontend behavior, monitoring, operations records, documentation, runbooks, CI/CD, Docker, Kubernetes, deployment, backups, security, or future AI-agent workflows.
This review is action-oriented. If the review identifies an issue that can be fixed safely inside the current task scope, the assistant or coding agent should fix and validate it before the commit. If the issue cannot be fixed safely before commit, it must be recorded as a generated follow-up task with enough context for a future human, AI session, automation worker, or operations database process to act on it.
Every commit and merge commit must also answer this question in its own subsection:
Has this commit revealed a weakness, ambiguity, missing safeguard, or repetitive manual step in the project standards or workflows?
The answer must state whether the issue was fixed before commit or deferred as a structured follow-up. It must not be hidden inside a generic risk note.
12. AI-Assisted Tooling Rules
AI agents should not add new tools or dependencies without explicit approval.
An AI agent may recommend a dependency, but implementation should require a scoped task.
For Codex implementation tasks, specify allowed files, forbidden files, whether dependency installation is allowed, whether lockfile changes are allowed, whether formatting is allowed, whether pipeline configuration may be changed, validation commands, and handoff requirements.
Lockfile changes should be intentional and reviewed.
Pipeline configuration changes should be intentional, scoped, and reviewed as high-impact automation changes.
13. Maintenance Requirements
Update this document when the Python project manager is initialized in the repository, tool configuration is added to project metadata, the first test suite is established, the linting rules are tightened, the first CI/CD pipeline is adopted, pipeline validation commands change, the database access layer is standardized, schema migration tooling is implemented, script execution conventions change, the project moves to Linux, or containerization is introduced.