Document Scope
This document is a short stack and architecture briefing for new AI development sessions. It should be provided near the beginning of a session that will generate code, review architecture, prepare Codex prompts, write documentation, refactor backend files, or propose new implementation work.
This document does not replace the full architecture standards, technology stack reference, repository structure guide, Git workflow standards, CI/CD pipeline standard, or task-specific handoffs. It is a compact orientation file that tells the AI session what kind of project it is working on and what tools, layers, and boundaries are already selected.
This document is written for ChatGPT sessions, Codex sessions, AI-assisted development tools, automation workers, and future AI agents.
1. Purpose
The purpose of this document is to prevent a new AI session from creating architecture randomly.
The project already has selected tools, selected layers, and selected direction. A new session should not recommend unrelated frameworks or restructure the backend based on generic assumptions. It should work within the chosen stack unless the user explicitly asks for a reevaluation.
This document also helps the user avoid re-explaining the stack in every session. Naming the selected tools gives an AI system useful context immediately.
2. Selected Stack Summary
Use this table as the primary stack map.
| Layer | Selected implementation |
|---|---|
| Python project manager | uv |
| Python linting and formatting | Ruff |
| Python testing | pytest |
| API layer | FastAPI |
| API contract | OpenAPI |
| Data validation and models | Pydantic |
| Structured configuration | Pydantic Settings |
| Database access | SQLAlchemy Core |
| Schema migrations | Alembic where compatible |
| Dynamic frontend applications | React, Next.js, TypeScript |
| Static public pages | HTML, CSS, JavaScript, Markdown-generated pages |
| Internal dashboards | Streamlit |
| Terminal output | Rich |
| Terminal applications | Textual only where justified |
| Customer authentication | Better Auth |
| Public bot protection | Turnstile Managed mode |
| Internal access | protected tunnel and identity-aware access |
| Scheduler | current operating-system scheduler; future scheduler not final |
| HTTP client for Python integrations | HTTPX |
| Brevo and Resend | |
| Object storage | provider-neutral object storage wrapper |
| Telegram | Telegram integration wrapper and Telegram APIs |
| Documentation | Markdown, Obsidian, Git-backed workflow |
| Diagrams | Mermaid |
| Templates | Jinja2 where generated text/templates are needed |
| Version control | Git |
| Remote Git host | GitLab currently |
| Remote Git CI/CD pipeline service | GitLab CI/CD currently |
| Pipeline configuration | repository-specific .gitlab-ci.yml where adopted |
| Lightweight monitoring tool | Watchdog (monitoring/watchdog.py) |
| Heavy monitoring/audit tool | Deep Audit (monitoring/feed_audit.ps1) |
| Current operating environment | Windows Server |
| Future operating environment | Linux VPS |
| Future containerization | Docker planned; review impact before commit once adopted |
The tool names above are the current selected implementations. In ordinary architecture text, use generic layer names such as API layer, database access layer, configuration layer, scheduler layer, and authentication layer.
2.1 Stack Selection Does Not Equal Artifact Approval
The selected stack table is an architecture orientation tool. It tells the AI which layers and tools are currently selected or planned. It does not authorize the AI to install, upgrade, import, mirror, copy, pull, or configure an artifact without supply-chain review.
A selected tool still requires artifact-level control when it enters a repository. The Supply Chain Security Standard controls official-source verification, version selection, package pinning, container-image digest pinning, signing, SBOM expectations, license review, Technology Decision Records, Supply Chain Records, Integration Records, and operator approval. The AI must not treat this brief as permission to run an install command or add a dependency.
3. Core Architecture Rules
Business logic belongs in reusable service modules.
Frontend applications, dashboards, terminal tools, API route handlers, and scripts should call service-layer logic. They should not duplicate business rules.
Database access should go through the standard database access layer.
Configuration should come from the central configuration layer.
Provider-specific services should be wrapped behind internal interfaces.
Repository automation should use the remote Git CI/CD pipeline service where appropriate. Each repository-related session must consider whether the pipeline should be created, updated, or explicitly left unchanged before commit readiness.
Staging and production must remain visibly separated.
The current monitoring tools are Watchdog and Deep Audit. Watchdog is the frequent lightweight operational monitor. Deep Audit is the heavier feed-quality and backlog audit. They are useful for troubleshooting, runtime health review, and operational baselines, but they are not generic commands to run casually.
Presentation layers should display data and collect input. They should not own core rules.
The scheduler choice is not permanent. Do not design the backend around the current scheduler.
4. Backend Restructuring Direction
The Python backend is being reorganized from loose scripts into a structured Python project.
The immediate direction is:
uv-managed project
importable packages
reusable service modules
centralized configuration
standard database access
explicit models
tests
thin scripts
API-ready service functions
dashboards and CLI tools that call services
The backend should not be broadly rewritten. Move one boundary at a time.
The completed first package-boundary milestone moved the database adapter into:
<workspace-root>/app/runtime/db_adapter.py
The active import pattern is:
from runtime import db_adapter
The old config-local database adapter should not be recreated unless the user explicitly requests a revert or emergency recovery action.
5. Repository and Documentation Expectations
The project uses a modular multi-repository workspace. The application/backend repository is only one repository inside the workspace. A future AI session must confirm which repository it is working in before editing files or giving Git commands.
Repository class controls how this stack applies. A deployable application repository, context/reference repository, infrastructure repository, and utility repository may all refer to the same selected tools, but they do not receive the same validation, CI/CD, release, SBOM, or deployment expectations. Classify the repository before applying stack guidance.
Durable path references should use:
<workspace-root>
Current Windows commands may use the current literal path when a runnable command is required.
Each deployable repository should move toward a repository-specific CI/CD pipeline. Pipeline configuration is high-impact repository automation and must not be created or modified casually. Before recommending a commit, review whether the recent change requires a pipeline update.
Documentation is source material. Markdown documents may be used for internal training, public document libraries, Command Center documents, runbooks, architecture records, and AI context.
Generated documents should use the project document format:
frontmatter properties
# Document Scope
## 1. Purpose
remaining numbered sections
6. Monitoring and Operational Baseline Tools
The current monitoring tools are:
Watchdog: <workspace-root>/app/monitoring/watchdog.py
Deep Audit: <workspace-root>/app/monitoring/feed_audit.ps1
Watchdog is the lightweight monitor. It is intended for frequent operational health review and currently checks feed processor health, database reachability, Telegram identity/channel access, latest Deep Audit result, domain/DNS health, incident sync, and alert behavior where configured.
Deep Audit is the heavier audit. It is intended for deeper feed-quality, backlog, public-output, and operational evidence review. It produces HTML, text, and JSON reports under the feed audit log directory.
These tools are often useful when troubleshooting. They are also scheduled in the current Windows environment, with Watchdog intended as the frequent check and Deep Audit intended as the less frequent heavier check. They should not be run automatically merely because a session starts.
Use the Runtime Validation Standard to decide whether to run either tool. If the task-specific handoff does not explicitly require Watchdog or Deep Audit, ask before running them.
The existing HTML monitoring runbooks remain useful background references but may be outdated in places. If a task requires exact current commands, schedules, report paths, or monitoring behavior and the startup documents are not enough, ask the operator for the current monitoring documentation, current terminal output, or current repository state before implementing changes.
7. Do Not Do These Things
Do not recommend Flask or Django as replacements for the selected API layer unless the user explicitly opens a new evaluation.
Do not replace the static public site with Streamlit.
Do not treat Streamlit as the main customer application framework.
Do not put business logic in frontend components.
Do not duplicate authentication logic in Python.
Do not bypass the database access layer for new work.
Do not hardcode provider-specific object storage logic throughout the codebase.
Do not treat the current scheduler as permanent.
Do not run production-mutating scripts unless the user explicitly approves.
Do not run Watchdog or Deep Audit automatically or casually. Use them only when the task requires them or the user approves them.
Do not ask Codex to perform broad cleanup or broad modularization.
Do not move files across repositories without explicit approval.
Do not create or modify CI/CD pipeline configuration unless the task explicitly scopes pipeline work, deployment permissions, secret/variable handling, validation jobs, and expected pipeline behavior.
8. Immediate Implementation Bias
When planning near-term backend work, prefer this order:
1. Establish or document uv project structure.
2. Add or document linting and formatting standards.
3. Add or document testing standards.
4. Add or document CI/CD pipeline expectations when repository automation is relevant.
5. Inventory existing scripts and imports.
6. Define package boundaries.
7. Move one boundary at a time.
8. Centralize configuration.
9. Standardize database access.
10. Add models where boundaries require them.
11. Add APIs on top of services.
12. Build dashboards and CLI tools on top of services.
If a user asks for a technical implementation, first confirm whether the task is documentation-only, inspection-only, or implementation.
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.
9. Review Triggers
Review this brief when a selected tool changes, CI/CD pipeline strategy changes, monitoring tool behavior changes, a scheduler decision is made, the backend package layout is finalized, the API layer is implemented, the database access layer is replaced or revised, the project moves from Windows to Linux, a new AI-agent workflow begins, or a new subscription service is created.