Daily Routine / AI Training

08 - Architecture Standards Draft

Internal architecture standards for the service platform, including layered design, reusable service modules, centralized database access, provider-neutral integration wrappers, environment-aware configuration, repository CI/CD automation, observability, template-ready subscription services, AI-agent safety boundaries, and documentation rules.

Text size
Status: draftCreated: 2026-07-03Last updated: 2026-07-05

Document Scope

The platform is being designed as a repeatable SaaS system with public pages, authenticated customer areas, internal administrative tools, background workers, database-backed operations, Telegram-based content delivery, repository CI/CD automation, repository-class-specific pipeline validation, context/reference libraries, documentation libraries, and future AI-agent-assisted maintenance.

This document defines the architecture standards that should guide new services, backend refactoring, database design, dashboards, APIs, integrations, operations tooling, documentation, and future AI-agent workflows. It is intended to be read before making structural changes or recommending new architecture.

This document uses generic layer terms throughout the body. The selected tools for those layers are defined near the beginning of the document so that a future change in implementation can be handled by updating a limited part of the documentation instead of rewriting every section.

1. Purpose

The purpose of this document is to prevent the platform from becoming a collection of one-off scripts, one-off dashboards, one-off database patterns, and one-off product implementations.

The first subscription service should be treated as the first implementation of a repeatable service pattern, not as a permanent hardcoded limit. Future services may cover different topics, niches, industries, or customer groups. The architecture should make future services easier to create by using shared modules, shared database infrastructure, shared API patterns, shared monitoring, shared documentation patterns, and service-specific configuration.

The central architecture goal is repeatability. A new subscription service should eventually be created by registering metadata, configuration, sources, rules, access mappings, delivery mappings, monitoring expectations, and documentation stubs. It should not require copying and rewriting the backend.

2. Layer and Tool Definitions

This table defines the selected implementation for each architecture layer. The rest of the document uses generic layer names unless the specific selected tool is necessary.

Architecture layer Current selected implementation Documentation term to prefer
Python project management uv Python project manager
Code quality Ruff linting and formatting layer
Testing pytest testing layer
API framework FastAPI API layer
API contract OpenAPI API contract
Data models Pydantic model layer
Configuration Pydantic Settings configuration layer
Database access SQLAlchemy Core database access layer
Schema migrations Alembic where compatible schema migration layer
Dynamic frontend React, Next.js, TypeScript frontend application layer
Static frontend HTML, CSS, JavaScript static site layer
Internal browser dashboards Streamlit internal dashboard layer
CLI presentation Rich terminal output layer
Interactive terminal apps Textual where justified terminal application layer
Customer authentication Better Auth customer authentication layer
Public bot protection Turnstile Managed mode bot-protection layer
Internal private access protected tunnel and identity-aware access internal access layer
Scheduler current operating-system scheduler; future scheduler undecided scheduler layer
Email internal email service wrapper email service layer
Object storage provider-neutral object storage wrapper object storage layer
Telegram Telegram integration wrapper around Telegram APIs Telegram integration layer
Remote repository automation remote Git CI/CD pipeline service; GitLab CI/CD currently CI/CD pipeline layer
Pipeline configuration repository-specific pipeline configuration file; .gitlab-ci.yml currently pipeline configuration
Deployable repository class app, site, admin, and future deployable repositories deployable repository
Server/infrastructure repository class server currently server/infrastructure repository
Context/reference repository class ctx-* repositories context/reference repository
Personal utility repository class echo and similar repositories personal utility repository
Documentation Markdown, Obsidian, publishing workflow documentation layer
Diagrams Mermaid diagram format

Specific implementation names should appear in decision tables, tool references, and implementation runbooks. The main architecture rules should speak in layer terms.

2.1 Repository Classification and Supply Chain Governance

Architecture work begins with repository classification. A deployable application repository, shared library repository, context/reference repository, utility repository, infrastructure repository, experimental repository, and archive/retired repository have different architectural obligations. The same tool or pattern may be correct in one class and inappropriate in another.

Architecture work also begins with supply-chain control. A technology may be architecturally selected, but a specific package, image, model, repository, CI/CD component, binary, or mirrored source remains unapproved until the Supply Chain Security Standard has been applied and the operator has approved the decision status.

Architectural recommendations must therefore separate these decisions:

Should this technology or layer exist in the architecture?
Can this specific external artifact be trusted and approved?
How is this approved artifact integrated into this repository?

The first question belongs in architecture and Technology Decision Records. The second belongs in Supply Chain Records and evaluation reports. The third belongs in Integration Records and repository-specific implementation work.

3. Core Architecture Rule

Business logic belongs in reusable service modules.

Business logic should not be embedded directly in API route handlers, frontend pages, dashboard files, terminal interfaces, command-line display scripts, one-off maintenance scripts, Telegram command handlers, or static website JavaScript.

Presentation layers may call services. They should not own the rules. This allows the same behavior to be reused by customer dashboards, admin tools, CLI utilities, internal dashboards, terminal applications, background workers, tests, and future AI agents.

A healthy architecture has this shape:

Presentation layer
    calls
API or script entry point
    calls
service-layer function
    calls
model/configuration/database/integration layers

A risky architecture has this shape:

presentation file
    directly opens database
    directly calls provider API
    directly implements business rules
    directly mutates production records

The second pattern should be avoided unless a narrow, documented exception exists.

4. Layered Architecture Standard

The platform should follow a layered architecture.

Presentation layer
API layer
Service layer
Domain and model layer
Database access layer
Integration layer
Operations and observability layer
Repository automation and CI/CD layer

Each layer has a distinct job.

The presentation layer displays data and collects input.

The API layer exposes backend capabilities through structured endpoints.

The service layer owns business workflows.

The domain and model layer defines structured data and contracts.

The database access layer owns query execution and database interaction patterns.

The integration layer wraps provider-specific services.

The operations and observability layer records what happened, what failed, what needs attention, and what can be remediated.

The repository automation and CI/CD layer runs remote validation, build, test, package, and deployment jobs through repository-specific pipeline configuration.

These layers may live in the same repository, but they should not be mentally collapsed into one undifferentiated script folder.

5. Presentation Layer Standard

Presentation layers include static pages, dynamic frontend applications, internal dashboards, terminal applications, terminal output, API documentation interfaces, and document-library pages.

A presentation layer may make a user experience easier. It may validate input for usability. It may format tables, charts, forms, cards, warnings, and status indicators. It may show environment labels, job state, service status, or operational summaries.

It must not become the source of truth for subscription rules, database rules, payment rules, Telegram publishing rules, incident remediation rules, authentication rules, or production write safety. Backend services must still enforce the real rules.

This rule applies equally to browser interfaces and terminal interfaces. A terminal script that uses a beautiful table is still a presentation layer if its job is to display output. It should call service-layer logic rather than owning the business workflow directly.

6. API Layer Standard

The API layer is the stable contract between clients and backend services.

API endpoints should generally accept a request, validate input, check authentication, check authorization, call a service-layer function, return a structured response, and record telemetry.

API route handlers should remain thin. They should not contain major workflows.

The API contract should be treated as part of the architecture. When request models, response models, endpoints, or error behavior change, the contract changes. This matters because customer dashboards, admin interfaces, tests, AI agents, and future tools will rely on the API contract.

Use ordinary request/response endpoints for normal data retrieval and updates. Use live connections only when live state is truly needed.

7. Service Layer Standard

The service layer owns use-case workflows.

Examples of service-layer responsibilities include creating a subscription service, validating customer access, processing incoming content, publishing a clean content item, creating a report, recording an operational incident, claiming a remediation job, sending a transactional email, writing an object storage artifact, comparing staging and production state, and building dashboard data.

A service-layer function should be written so that it can be called by multiple entry points. The same function may be used by an API endpoint, a scheduled worker, a CLI utility, an internal dashboard, a terminal app, a test, or a future AI agent.

Reusable services are the foundation for future scale. If each entry point implements its own rules, the platform will drift.

8. Domain and Model Layer Standard

The model layer makes data explicit.

Models should define structured records used across the system. Important examples include subscription service records, customer account references, subscription plans, content items, Telegram message records, processing results, operations incidents, remediation jobs, report artifacts, API requests, API responses, and configuration objects.

Explicit models reduce ambiguity. They also make the system easier for humans and AI agents to reason about because data structures no longer need to be inferred from loose dictionaries or scattered JSON handling.

The model layer should grow gradually. Do not rewrite every dictionary immediately. Add models where they reduce risk, clarify boundaries, or support a new API/service contract.

9. Database Access Standard

All database access should go through the approved database access layer unless a documented exception exists.

Application code should not casually open raw database connections, create unrelated cursor patterns, scatter SQL execution, or implement transaction handling independently in many files.

The database access layer should provide standard behavior for connection handling, transaction handling, query execution, parameter binding, error handling, query timing, metrics, logging, health checks, and environment separation.

This standard does not mean the existing database code should be rewritten all at once. It means new work and refactors should move toward one shared database access pattern.

Database changes are high risk because they touch persistent state. They must be staged, reviewed, tested, and documented.

10. Configuration Standard

Configuration must be centralized.

Modules should not independently parse environment variables, local files, secrets, or runtime mode flags in unrelated ways. The configuration layer should provide validated settings for environment identity, database access, Telegram integration, email service, object storage, scheduler behavior, feature flags, logging, and provider credentials.

Production must not be the accidental default for write-capable scripts. Any tool that can write data should make the current environment visible.

Configuration should be designed for the current Windows environment and the future Linux environment. Durable configuration code should not hardcode Windows-only paths unless the task is explicitly machine-specific.

11. Integration Wrapper Standard

Provider-specific integrations must be wrapped where practical.

This applies to object storage, email, Telegram, infrastructure APIs, external content APIs, AI providers, payment providers, and authentication integration points.

Application code should call internal service wrappers rather than scattering provider calls across the repository. For example, application code should call an internal email service instead of directly embedding provider-specific SMTP logic in many unrelated files.

Wrappers preserve future portability. If a provider changes, the wrapper can change while the rest of the application continues to call the same internal interface.

12. Scheduler Standard

The scheduler layer is a capability, not a permanent commitment to one scheduler product.

The current scheduler is the current operating-system scheduler because the platform currently runs on Windows. This is acceptable as an operating reality. It should not be written into architecture documents as the permanent scheduling strategy.

Future scheduling may use a different tool after the platform moves to a Linux VPS, adopts cleaner service modules, centralizes configuration, and standardizes worker identity and operations visibility.

Regardless of the scheduler tool, scheduled jobs must have clear names, clear commands, clear environment identity, documented purpose, logged start and finish, logged failures, retry limits, idempotency where needed, operations visibility, and safe production behavior.

The scheduler decision should be revisited when the deployment model changes or when scheduled work needs to be controlled from application code.

13. Repository Automation and CI/CD Standard

The CI/CD pipeline layer is part of the normal repository architecture.

Pipeline expectations depend on repository class.

Deployable repositories, including the application backend, public site, private admin/command-center site, and future production-bound repositories, should move toward repository-specific pipeline configuration. Those pipelines should begin with low-risk validation jobs and expand over time into test, build, package, artifact, staging deployment, release, rollback, and manual production deployment workflows as the repository matures.

The server/infrastructure repository should begin with validation and dry-run checks for configuration, scripts, service definitions, scheduled-job definitions, tunnel configuration, future service units, bootstrap scripts, and environment documentation. Production infrastructure mutation must not be automated unless the task explicitly authorizes that class of automation.

Context/reference repositories using the ctx-* prefix are not runtime application repositories. They are reference libraries for humans, ChatGPT sessions, Codex sessions, future AI agents, and local retrieval workflows. They should have the simplest useful pipeline: documentation/reference structure checks, required index or manifest checks where present, Markdown/frontmatter checks where useful, no-secret checks, and no deployment jobs.

The CI/CD pipeline should not be introduced as a broad automation rewrite. Start with the smallest useful remote validation gate for the repository class.

A repository session should always consider pipeline impact before commit readiness. The session should ask whether the current change affects dependencies, validation commands, package layout, scripts, tests, build steps, deployment behavior, database migration behavior, environment variables, secrets, documentation structure, reference-library structure, or repository structure.

The answer may be that no pipeline change is required. That conclusion should still be considered and recorded when the task is repository-related.

CI/CD does not replace local validation. Local validation proves the working tree behaves correctly in the local environment. CI/CD validation proves the remote repository can reproduce required checks in a clean pipeline environment.

Production deployment must not be automated casually. Validation jobs may run automatically. Build jobs may run automatically after they are safe. Staging deployment may be automated after review. Production deployment should require a manual gate unless a later standard explicitly approves a different rule.

Pipeline configuration is high-impact repository code. It can run commands, consume secrets, publish artifacts, deploy services, modify infrastructure, run database migration commands, or mutate environments. Codex and AI agents must not create or modify pipeline configuration unless the task explicitly scopes that work.

Architectural Impact Review Standard

Repository work must include an Architectural Impact Review before commit readiness. The review is broader than CI/CD. CI/CD pipeline impact remains mandatory, but it is one part of a larger checkpoint that asks whether the completed work changed, weakened, contradicted, or exposed anything else that should be fixed before the repository checkpoint is created.

The Architectural Impact Review is not merely an information-gathering exercise. After the review identifies an affected area, the assistant or coding agent must decide whether the issue can be addressed safely inside the current task scope before the commit. If it can be fixed safely and the file scope allows it, the fix should be made and validated before commit. If it cannot be fixed safely, is outside the approved file scope, requires operator approval, touches production, requires a separate branch, or would mix unrelated work into the checkpoint, 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.

Before commit readiness, ask the following questions in full and answer them based on the actual diff, validation output, repository class, and task scope:

  1. Did dependencies, dependency groups, lockfiles, package manager configuration, Python version files, Node package files, or build-tool files change?
  2. Did the approved Python runner, script execution method, project metadata, virtual environment assumptions, or local setup instructions change?
  3. Did linting, formatting, type-checking, test discovery, test commands, test fixtures, or validation commands change?
  4. Did package layout, module layout, imports, entry points, service boundaries, script locations, or runtime command paths change?
  5. Did startup commands, worker commands, scheduler commands, service names, process names, ports, hostnames, tunnels, local preview routes, or health-check routes change?
  6. Did configuration loading, settings models, environment identity, environment variables, example configuration files, secret names, protected variables, or ignored private files change?
  7. Did database access, query behavior, transaction handling, schema, migration files, seed data, staging/production separation, or database safety assumptions change?
  8. Did object storage behavior, report artifact paths, stable links, retention behavior, backup behavior, archive behavior, or recovery procedures change?
  9. Did API routes, request models, response models, authentication checks, authorization checks, OpenAPI output, dashboard contracts, or frontend/backend integration expectations change?
  10. Did frontend build behavior, static-site generation, public assets, internal dashboard behavior, browser-visible routes, accessibility behavior, or customer-facing copy change?
  11. Did Telegram intake, processing, deduplication, AI rewriting, delivery, channel routing, customer-visible output quality, or provider-call behavior change?
  12. Did email, alerting, notifications, operational reports, incident creation, remediation jobs, or AI-agent work queues change?
  13. Did monitoring, Watchdog, Deep Audit, logs, metrics, operations records, health checks, failure reporting, or observability expectations change?
  14. Did deployment behavior, release behavior, rollback behavior, staging behavior, production behavior, infrastructure mutation, or manual deployment gates change?
  15. Did repository structure, documentation structure, context/reference library structure, generated documentation, README material, runbooks, handoff files, or operator procedures change?
  16. Did CI/CD pipeline configuration, pipeline stages, jobs, images, caches, artifacts, runner assumptions, pipeline variables, protected variables, deployment gates, or expected pipeline behavior after push change?
  17. Did Docker, Compose, container build assumptions, .dockerignore, image startup commands, container environment variables, mounted paths, exposed ports, health checks, or container validation need to be created or updated because of the work?
  18. Did Kubernetes, service manifests, deployment manifests, secrets handling, config maps, ingress, jobs, cron jobs, probes, namespaces, or cluster deployment assumptions need to be created or updated because of the work?
  19. Did the work create or reveal any security, privacy, access-control, secret-handling, production-safety, customer-impact, or data-retention concern?
  20. Did the work create or reveal any documentation mismatch, stale standard, stale runbook, stale local command, stale Codex prompt template, stale validation command, or stale startup instruction?
  21. Did the work reveal a repetitive manual step that should become a helper script, verifier, CI/CD job, documentation rule, runbook step, or future automation-worker task?
  22. Did the work reveal a weakness, ambiguity, missing safeguard, or process gap in the project standards, repository workflow, validation model, commit-message model, or AI-agent operating instructions?
  23. Which of the identified issues can be fixed safely before this commit without broadening the task improperly?
  24. Which identified issues must be recorded as generated follow-up tasks, and what exact future action should be taken?
  25. What should the operations database or future AI-worker layer be able to extract from this checkpoint?

Use this compact review format before commit readiness:

Architectural impact review:
- Repository class:
- Runtime behavior changed: yes/no.
- Validation behavior changed: yes/no.
- Configuration or secrets changed: yes/no.
- Database or persistent state changed: yes/no.
- API, frontend, dashboard, or customer-visible contract changed: yes/no.
- Monitoring, operations, reports, or AI-agent records changed: yes/no.
- CI/CD impact: yes/no.
- Docker impact: not adopted/no/yes/follow-up.
- Kubernetes impact: not adopted/no/yes/follow-up.
- Deployment or infrastructure impact: yes/no.
- Documentation or runbook impact: yes/no.
- Immediate fixes made before commit:
- Follow-up tasks generated:
- Reason unresolved items were deferred:

The review must be written in full, human-readable sentences when entered into a commit message, merge commit message, Codex handoff, or state handoff. Short labels may be used in the pre-commit working summary, but the durable record must preserve enough context for later recovery, operations database ingestion, and future AI-agent action.

Workflow Weakness and Safeguard Review

Every commit must explicitly answer this question:

Has this commit revealed a weakness, ambiguity, missing safeguard, or repetitive manual step in the project standards or workflows?

This answer must not be buried inside a generic risk section. It must be recorded as its own subsection in the commit message or merge commit message. If the answer is yes, the assistant or coding agent must identify what created the weakness, where it exists, why it matters, whether it was remediated before commit, and what follow-up remains. If the answer is no, the durable record must say that no workflow weakness, ambiguity, missing safeguard, or repetitive manual step was identified from this change.

When a weakness or repetitive manual step is identified, the assistant must immediately ask whether it can be safely fixed before commit. The default action is to fix it now when the fix is inside scope, low risk, validated, and does not mix unrelated work into the checkpoint. If the fix is not safe to include now, it must become a generated follow-up task, not an informal note.

14. Operations and Observability Standard

Every subsystem should emit useful operational information.

The operations layer should eventually support future AI agents that inspect system records and determine what needs attention. That requires structured, actionable information rather than vague logs.

A useful operations record should identify the component, environment, service, time, failure reason, affected record, retry state, suggested remediation, and whether automation may act safely.

Operations records should support health checks, incidents, jobs, remediation, audit trails, worker state, report generation, object storage publication, Telegram publishing, database health, API health, and scheduler health.

Observability is not optional. A system that cannot explain what happened is hard for both humans and AI agents to operate.

15. Subscription Service Standard

The platform must support repeatable subscription-service creation.

A subscription service should be treated as a configurable product unit. It should eventually have a service ID, internal name, public display name, description, topic, pricing/access mapping, source mapping, delivery mapping, processing rules, monitoring rules, documentation links, and active/inactive state.

Reusable infrastructure should not be hardcoded to the first product instance. Use generic names where the code applies to any subscription service. Preserve product-specific names only where the context is actually product-specific.

The preferred long-term pattern is:

generic service engine
+ service-specific configuration
+ service-specific source mappings
+ service-specific delivery mappings
+ service-specific pricing and access rules
= new subscription service

Future service creation should become increasingly template-driven and data-driven.

16. Telegram Pipeline Standard

Telegram is core product infrastructure.

The Telegram pipeline should be understood in stages: source intake, raw storage, processing, classification, deduplication, quality checks, publishing, post-publish verification, and monitoring.

Raw intake channels and clean customer-facing delivery channels must remain clearly separated.

Publishing must be idempotent and logged. Before customer-facing publication, the system should know the source content, processing result, target service, target channel, deduplication status, publication status, failure status, and retry status.

Service-specific publishing rules should be configuration-driven where practical.

17. Testing and Code Quality Standard

Automated tests and code-quality tooling are part of the architecture.

Testing should begin with critical paths rather than attempting full coverage immediately. Critical tests should cover content intake, publication safety, deduplication, database writes, operations incidents, remediation jobs, configuration loading, environment separation, API responses, and auth boundaries.

Code-quality tooling should enforce consistent style and reduce drift. This is especially important when multiple AI systems generate or edit code over time.

A refactor that changes core behavior should include or update tests where practical.

18. Documentation Standard

Documentation is part of the system.

Markdown should be treated as source material. Documents may be used as AI context, internal notes, public documentation, Command Center documentation, runbooks, architecture records, and implementation handoffs.

Important architecture decisions should be documented as decision records. A decision record should include the decision, context, alternatives, reason selected, tradeoffs, and review triggers.

Durable architecture documents should use provider-neutral terms and define the selected implementation near the top. This makes documentation easier to maintain when a tool or provider changes.

19. AI-Agent Standard

The platform is being designed for future AI-agent operation.

AI agents need clear folder structure, service boundaries, configuration, database access patterns, API contracts, logs, operations records, tests, runbooks, and safety boundaries.

Future AI agents should use approved interfaces such as APIs, service-layer functions, operations database jobs, CLI tools, documented scripts, and controlled admin tools.

AI-agent actions should be logged like human administrator actions. Logs should identify the agent, action, target service, environment, inputs, result, error, verification outcome, and rollback action if any.

No AI agent should have vague authority to change everything.

20. What Not To Do

Do not put business logic directly in UI files.

Do not let API route handlers become giant workflows.

Do not let internal dashboards mutate production data casually.

Do not let scripts open random database connections with no shared helper layer.

Do not duplicate authentication logic in Python when the authentication layer is the source of truth.

Do not hardcode one subscription service into reusable infrastructure.

Do not hardcode provider-specific object storage assumptions everywhere.

Do not scatter email-provider logic across the codebase.

Do not write production scripts that fail to identify the environment.

Do not create new databases without documenting ownership and purpose.

Do not add frameworks merely because they are popular.

Do not use future containerization to hide poor structure.

Do not treat CI/CD as optional once a repository begins moving toward deployment or repeatable validation.

Do not give context/reference repositories deployment pipelines.

Do not automate production deployment without an explicit manual gate and approved deployment standard.

Do not allow AI agents to operate without scope, logs, or safety boundaries.

21. Review Triggers

Review this document when the first paid subscription service becomes stable, a second subscription service is created, a new database layer is added, a repository is added or changes class, a repository adopts or materially changes its CI/CD pipeline, the project moves from Windows to Linux, containerization is introduced, the authentication layer is implemented, the future identity provider layer is introduced, PostgreSQL or another major database is introduced, AI agents begin automated operations, a major provider is replaced, the Command Center becomes production-critical, or production incidents reveal missing standards.

22. Summary

The platform must be designed for repeatability.

The first subscription service is the prototype for every future subscription service. The architecture should make it possible to launch new services by assembling existing standardized components rather than rebuilding the backend.

The core principles are: keep business logic in services, keep database access centralized, keep frontend clients behind APIs, keep provider-specific logic wrapped, keep configuration centralized, keep repository CI/CD pipelines aligned with repository class, validation, and deployment needs, keep every subsystem observable, keep presentation layers separate from business rules, keep subscription services data-driven and template-ready, and keep AI-agent operation in mind.