Document Scope
The platform uses a layered technology stack that includes static public pages, dynamic frontend applications, backend APIs, reusable Python service modules, database infrastructure, authentication, bot protection, scheduling, operations tooling, remote Git CI/CD pipeline automation, Telegram-based delivery, email, object storage, documentation publishing, and future AI-agent workflows.
This document defines the current technology stack in a way that can train future human developers, ChatGPT sessions, Codex sessions, AI-assisted development tools, automation workers, and future AI agents. It identifies the selected tool or framework for each functional layer, but the body of the document uses generic layer terms wherever practical so that the document remains durable if a vendor, framework, or provider changes later.
This document is not a complete implementation plan. It does not authorize immediate refactoring, database migration, framework installation, or deployment changes. It is a stack reference and training document. Implementation must still happen through scoped repository tasks, branch-first Git work, validation, and documented handoffs.
1. Purpose
The purpose of this document is to give every future development session a clear map of the selected tools and the job each tool is expected to perform.
The platform is not a single script, a single website, or a single dashboard. It is a modular SaaS platform with public pages, authenticated customer areas, internal administrative tools, scheduled workers, database-backed processing, operational telemetry, document libraries, and Telegram-based content delivery. A future AI session should not invent a new stack each time it starts work. It should understand that the project has selected tools, selected layers, and selected boundaries.
This document also prevents one tool from expanding into another tool’s job. For example, the internal dashboard layer should not become the core business-logic layer. The frontend application layer should not own backend database rules. The database layer should not be bypassed by random direct connections. The scheduler layer should not be hardcoded permanently to the current operating system. Each layer has a purpose.
2. Selected Tool Map
The following table defines the current selected tool, provider, framework, or resource for each generic platform layer. The generic layer term should be used throughout durable documentation unless the specific selected tool matters.
| Generic layer term | Current selected tool, framework, or resource | Status |
|---|---|---|
| Python project manager | uv |
Selected foundation |
| Python linting and formatting layer | Ruff | Selected foundation |
| Python testing layer | pytest | Selected foundation |
| API layer | FastAPI | Selected standard |
| API contract format | OpenAPI, exposed through FastAPI-generated documentation | Selected standard |
| Request/response and internal model layer | Pydantic | Selected standard |
| Structured configuration layer | Pydantic Settings | Selected standard |
| Database access layer | SQLAlchemy Core | Selected standard, adopt incrementally |
| Schema migration layer | Alembic | Selected where compatible with the adopted database path |
| Dynamic frontend application layer | React with Next.js and TypeScript | Selected direction |
| Public static site layer | HTML, CSS, JavaScript, Markdown-generated pages | Active standard |
| Internal browser dashboard layer | Streamlit | Selected for internal dashboards and data tools |
| Terminal output layer | Rich | Selected for readable command-line output |
| Interactive terminal application layer | Textual | Optional/future, use when terminal UI is justified |
| Customer authentication layer | Better Auth | Selected, keep boundary clean |
| Public bot-protection layer | Turnstile Managed mode | Selected |
| Internal access layer | Protected tunnel and identity-aware access | Active standard |
| Future internal identity provider layer | Dedicated SSO/identity provider, currently authentik as planning candidate | Future planning item |
| Current scheduler layer | Windows Task Scheduler | Current operating reality |
| Future scheduler layer | Undecided; Python-native scheduler may be evaluated later | Deferred decision |
| Python HTTP client layer | HTTPX | Selected for new Python HTTP integrations where appropriate |
| Email service layer | Internal email wrapper with current primary and fallback providers (Brevo and Resend) | Selected pattern |
| Object storage layer | Provider-neutral object storage wrapper | Selected pattern |
| Current object storage implementation | S3-compatible object storage provider | Active implementation |
| Telegram integration layer | Telegram Bot API and controlled internal wrappers | Core product infrastructure |
| Documentation source format | Markdown | Selected standard |
| Documentation editor/workflow | Obsidian and Git-backed Markdown workflow | Selected workflow |
| Diagram format | Mermaid | Selected diagram format |
| Template generation layer | Jinja2 where generated text, email, Markdown, HTML, or reports are needed | Selected where appropriate |
| Version control | Git | Selected standard |
| Remote Git host | GitLab currently | Current implementation |
| Remote Git CI/CD pipeline service | GitLab CI/CD currently | Selected repository automation layer |
| Pipeline configuration file | .gitlab-ci.yml per repository where adopted |
Repository-specific validation, build, package, deploy, and release automation |
| Main editor | Visual Studio Code | Current editor |
| Visual Git client | GitKraken | Current support tool |
| Mobile Git workflow | Working Copy | Planned/selected mobile workflow |
| Current operating environment | Windows Server | Current reality |
| Future operating environment | Linux VPS | Planned future direction |
| Future containerization layer | Docker | Planned future layer; review impact before commit once adopted |
The “current selected tool” column is intentionally isolated in this section. Later sections use generic layer names such as API layer, database access layer, scheduler layer, and authentication layer. If a tool changes later, update this table first and then review only the places where the specific tool is truly material.
2.1 Selected Stack, Approved Stack, and Approved Artifacts
The selected tool map identifies the architecture direction. It does not by itself approve every package, image, plugin, workflow, model, binary, or remote source associated with those tools.
The project distinguishes between three related concepts:
selected stack layer
means the architecture has chosen a tool or pattern for a functional role
approved stack pattern
means the layer is part of the current platform direction
approved artifact
means a specific package, image, version, digest, model, binary, repository, or external component has passed supply-chain review and operator approval
For example, Docker may be the planned containerization layer, but a specific base image must still pass the Supply Chain Security Standard before it is used. A Python package manager may be selected, but a specific package version and lockfile change still require supply-chain discipline. An AI model or MCP server may be useful, but it remains unapproved until evaluated.
Future AI sessions must not use this stack reference as a blanket installation list. It is a map of architectural choices, not a bypass around artifact evaluation.
3. Provider-Neutral Documentation Rule
Durable internal documentation should use provider-neutral terms unless the specific vendor or framework is necessary.
Use terms such as object storage, remote Git host, SQL database, API layer, authentication layer, scheduler layer, internal access layer, email service, and documentation publishing workflow.
Do not repeatedly hardcode provider or product names throughout the document body unless the topic is specifically about that provider or product.
This rule exists because the platform is expected to evolve. The current object storage provider may change. The current remote Git host may change. The current scheduler may change when the project moves from Windows to Linux. The current authentication framework may be replaced later. Durable documentation should not require dozens of edits merely because one implementation changes.
Specific names are still allowed in definition tables, decision records, implementation guides, and provider-specific runbooks. They should not be scattered unnecessarily throughout generic architecture standards.
4. Layered Stack Summary
The long-term platform architecture should be understood as a stack of layers.
Presentation layers
Static public pages
Dynamic frontend applications
Internal browser dashboards
Terminal interfaces
CLI output
Future AI-agent interfaces
API layer
REST endpoints
WebSocket endpoints where live updates are required
OpenAPI contract
Service layer
Reusable backend business workflows
Subscription-service logic
Telegram pipeline behavior
Reporting workflows
Operational workflows
Email and storage use cases
Domain and model layer
Request models
Response models
Internal records
Configuration models
Service contracts
Database access layer
Query execution
Connection handling
Transaction handling
Query timing
Error handling
Metrics
Health checks
Integration layer
Telegram
Email
Object storage
External APIs
Infrastructure provider APIs
AI providers
Payment providers
Repository automation layer
Remote pipeline validation
Build automation
Artifact handling
Staging deployment
Manual production deployment gates
Operations and observability layer
Structured logs
Health status
Incidents
Jobs
Metrics
Remediation records
Audit trails
This stack is a decision framework. When a future session writes code, it should first identify the layer. The layer determines which tool is appropriate and where the code should live.
5. Public Static Site Layer
The public static site layer is for public information that does not require server-side execution or user-specific data.
This layer is appropriate for marketing pages, pricing pages, public support pages, public documentation, service explanation pages, and doorway pages into authenticated areas. Static pages should remain static where possible because static hosting is simple, fast, inexpensive, and operationally stable.
The public static site layer should not own authentication logic, subscription rules, backend database access, Telegram publishing, customer-specific dashboard behavior, or operational tools. When a public static page needs dynamic behavior, it should link to or call an approved dynamic layer rather than becoming a second backend.
6. Dynamic Frontend Application Layer
The dynamic frontend application layer is for authenticated customer dashboards, structured administrative interfaces, account pages, billing/status pages, configuration screens, charts, telemetry displays, and reusable interface components.
The frontend application layer should render data, collect input, manage user interaction, and consume APIs. It should not own backend business logic. It should not bypass the API layer to reach databases directly.
Use this layer when the interface needs structured routes, reusable components, authenticated views, stateful dashboard behavior, forms, charts, or a modern customer/admin application structure.
7. API Layer
The API layer is the stable contract between clients and backend services.
The API layer should expose backend capabilities to customer dashboards, admin applications, internal dashboards, CLI tools, future mobile applications, automation workers, and future AI agents. The API layer should validate requests, check authentication and authorization, call service-layer functions, return structured responses, and emit telemetry.
API route handlers should stay thin. A route handler should not become a large workflow. Business rules belong in reusable service modules so that the same behavior can be called by APIs, workers, dashboards, command-line tools, tests, and AI agents.
REST should be the default request/response pattern. WebSockets should be reserved for live state where a persistent browser connection is actually useful, such as live pipeline status, queue movement, incidents, job progress, or operational telemetry.
8. Service Layer
The service layer is where backend business workflows belong.
A service-layer function might create a subscription-service record, verify customer access, process an incoming content item, publish a clean item, generate a report, create an operations incident, send an email, write an object storage artifact, reconcile records, or register a remediation job.
The same service-layer function should be reusable from multiple entry points. An API route, scheduled worker, CLI script, internal dashboard, terminal app, or future AI agent should be able to call the same business workflow rather than reimplementing it.
This layer is central to long-term maintainability. If business logic is scattered into presentation files, route handlers, scripts, and dashboards, the platform will become hard to test and hard for AI agents to understand.
9. Domain, Model, and Configuration Layers
The model layer defines the shape of data passed through the system.
Models should be used where data crosses boundaries: API requests, API responses, service inputs, service outputs, configuration objects, operations records, database result transformations, Telegram records, email requests, report metadata, and subscription-service definitions.
The configuration layer should centralize environment-specific behavior. Individual modules should not independently parse unrelated environment variables. The configuration layer should expose validated settings for environment identity, database settings, Telegram settings, email settings, object storage settings, scheduler settings, feature flags, and logging behavior.
This matters because staging and production must remain separated. Scripts and tools that can write data must make the target environment visible and must not accidentally default to production.
10. Database Access and Schema Layers
The database access layer is responsible for how application code reaches structured storage.
Application code should not scatter raw connection creation, transaction behavior, error handling, timing, retry behavior, and query execution across unrelated files. The database access layer should provide a consistent way to execute queries, bind parameters, handle errors, record timing, distinguish staging from production, and expose database health information.
The schema migration layer is responsible for controlled database changes. Schema changes should become version-controlled, reviewable, repeatable, tested in staging before production, and documented.
The database access layer and schema migration layer should be adopted incrementally. Existing working behavior should not be rewritten broadly merely to satisfy an architecture document. The correct path is staged migration, validation, and preservation of working runtime behavior.
11. Scheduler Layer
The scheduler layer is intentionally not permanently tied to one scheduler tool.
The current operating environment uses the current operating system’s scheduler. This is acceptable while the project runs on the current Windows server. Later, when the platform moves to a Linux VPS or a more service-oriented deployment model, the scheduler layer may change.
Durable documentation should therefore refer to the scheduler layer rather than hardcoding one scheduler product everywhere.
Scheduler-related standards should focus on behavior: jobs have names, jobs have environments, jobs have clear start commands, jobs log results, jobs report health, jobs avoid unsafe duplicate work, jobs have retry limits, jobs expose failure reasons, and jobs are visible to operations tooling.
A future Python-native scheduler may be evaluated when the backend structure, configuration layer, service modules, and operations visibility are mature enough. The scheduler decision should not lead the architecture. It should follow a cleaner backend structure.
12. Operations Tooling Layers
The internal browser dashboard layer, terminal output layer, and interactive terminal application layer are presentation tools for operators and administrators.
The internal browser dashboard layer is useful for data views, metrics, reports, database inspection, staging/production comparisons, pipeline status, and manual review tools.
The terminal output layer is useful for diagnostics, validation reports, operational summaries, progress displays, and command-line scripts.
The interactive terminal application layer is optional and should be used only when a keyboard-driven terminal interface is actually useful. It should not be adopted merely because it exists.
All of these tools should call shared backend services. They should not duplicate business logic or database access rules.
13. Authentication, Access, and Bot Protection Layers
The customer authentication layer owns customer login, sign-up, sign-out, session handling, and account authentication.
The internal access layer protects private server-hosted tools and administrative routes.
The bot-protection layer protects public unauthenticated forms from abuse.
These layers are related but not identical. A future AI session must not confuse them.
Customer authentication is not the same thing as internal administrative access. Bot protection is not the same thing as login. The internal access layer protects the path to private tools, while application-level authorization may still be needed inside those tools as the system grows.
14. Integration Layers
Provider-specific services should be wrapped behind internal interfaces.
This applies to email, object storage, Telegram, external APIs, infrastructure APIs, AI providers, and payment providers. The rest of the application should call internal service wrappers instead of scattering provider-specific code across the repository.
The wrapper rule gives the project future portability. If a provider changes, the internal wrapper can change while the rest of the application continues to call the same service interface.
15. Repository Automation and CI/CD Layer
The repository automation layer uses the remote Git CI/CD pipeline service to validate, test, build, package, and eventually deploy repository changes.
Each deployable repository should move toward a repository-specific pipeline configuration. The pipeline should start with low-risk validation jobs and expand over time into build jobs, artifact handling, staging deployment, manual production deployment gates, and release or rollback automation.
Pipeline configuration is high-impact repository code because it can run commands, consume protected variables, publish artifacts, deploy services, modify infrastructure, or affect databases. It should not be created or changed casually.
Every repository-related session should consider CI/CD impact before commit readiness. The correct question is:
Does this change require the pipeline to be created, updated, or explicitly left unchanged?
Local validation and pipeline validation are separate gates. Local validation proves the working tree passed checks in the local environment. Pipeline validation proves the remote repository can reproduce required checks in a clean automated environment.
Production deployment must not be automated casually. Validation and build jobs may run automatically when safe. Production deployment should remain manually gated unless a later deployment standard explicitly approves a different model.
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.
16. Documentation and Knowledge Layers
Markdown is the source format for internal documents, AI context, runbooks, architecture records, public documentation, and Command Center documentation.
Documents should be written as durable training material for humans and AI sessions. A document should not merely record that a decision happened. It should explain the current rule, the role of each layer, the selected tool map, and the safe boundaries for future work.
Architecture diagrams should be written in a Markdown-compatible diagram format where helpful. Diagrams should live beside the text that explains them so they remain version-controlled and easy to update.
17. Future AI-Session Training Use
This document should be provided early in a new AI development session.
A future session should understand these facts before proposing architecture: the project has a selected stack, the project is layered, business logic belongs in reusable services, frontend code consumes APIs, database access goes through a standard layer, configuration is centralized, provider-specific services are wrapped, repository automation belongs in the CI/CD pipeline layer, scheduler choice is not permanent, presentation tools do not own business rules, documentation is source material, and AI agents are expected future operators.
This training context is more efficient than a long prompt because naming the selected tools gives an AI session a large amount of architectural information immediately.
18. Maintenance Requirements
Update this document when a selected foundational tool is replaced, a layer receives a new standard tool, CI/CD pipeline strategy changes, the scheduler decision changes, the authentication framework changes, the database access standard changes, the API framework changes, the frontend framework changes, a provider-specific implementation becomes a generic interface, a future tool moves from candidate to selected, or a selected tool proves unsuitable and is retired.
When a tool changes, first update the selected tool map in Section 2. Then review the document body only where the specific tool is material.