Documentation Hub

This repository maintains a structured documentation library covering the full development lifecycle. All rule documents live in the docs/rules/ directory. This index maps each file to its technical domain and intended reader.

Technical Document Index

Section I: Foundation and Environment

01 Project Overview
- File: 01-project-overview.md
- Scope: System goals, business domain, deployment models, and what is and is not in this repository.
02 Tech Stack
- File: 02-tech-stack.md
- Scope: Frameworks, languages, libraries, runtime environments, and third-party integrations.
03 Commands
- File: 03-commands.md
- Scope: CLI reference, development triggers, testing commands, linting, and dependency management.

Section II: Architecture and Logic

04 Design Patterns
- File: 04-design-patterns.md
- Scope: Project-specific structural, creational, and behavioral patterns: Module, Chain, Event, Oper, Config Reload, Singleton.
05 Architecture and Modules
- File: 05-architecture.md
- Scope: Layer boundaries, dependency directions, module categories, and the canonical call graph.
09 External APIs, Protocols, and Responses
- File: 09-external-response.md
- Scope: HTTP client conventions, MCP protocol, standardized response formats, and error handling by layer.
10 Data and Persistent Management
- File: 10-data-and-persistent.md
- Scope: SQLAlchemy models, Alembic migrations, Oper access layer, SystemConfig, caching patterns.

Section III: Implementation Standards

06 Code Standards and Style
- File: 06-code-styles.md
- Scope: Type annotations, Pydantic usage, async patterns, imports, formatting, and error handling rules.
07 Naming Conventions
- File: 07-naming-conventions.md
- Scope: Strict taxonomy for files, classes, functions, constants, and schema models.
08 Comments and Documentation Style
- File: 08-comment-styles.md
- Scope: Chinese docstring requirements, inline comment rules, and prohibited comment anti-patterns.

Section IV: Quality and Governance

11 Code Quality and Security
- File: 11-quality-and-security.md
- Scope: Testing requirements, pylint gates, safety scans, authentication patterns, and input validation rules.
12 Collaboration, Versioning, Build, and Release
- File: 12-collaboration-and-distribution.md
- Scope: Conventional Commits, branch policy, release workflow, Docker build, and version management.

Reader Persona Guidance

Core Developers and Implementers

Developers actively writing or modifying features should follow this reading path:

07 Naming Conventions — establishes the lexicon for the feature.
06 Code Standards — ensures linting and logic compliance.
04 Design Patterns — identifies the correct structural approach.
03 Commands — required for local execution and validation.

System Architects and Reviewers

Personnel focused on system integrity and long-term maintenance:

05 Architecture and Modules — for verifying structural boundaries.
10 Data and Persistent Management — for auditing data integrity and storage efficiency.
09 External APIs — for reviewing integration security and protocol compliance.
11 Code Quality and Security — for establishing the PR approval baseline.

Operations and Release Engineers

Those managing the application lifecycle post-development:

12 Collaboration and Versioning — for release tags and branch management.
02 Tech Stack — for environment provisioning and dependency management.
11 Code Quality and Security — for verifying deployment-ready security posture.

Document Interconnectivity

Architecture (05) references Code Standards (06) for layer isolation and module boundary rules.
Naming Conventions (07) works in tandem with Comment Styles (08) to define overall code readability.
External APIs (09) relies on Tech Stack (02) for transport layer specifications and HTTP client selection.
Data Management (10) is governed by Quality and Security (11) for sensitive data handling requirements.
Design Patterns (04) is the implementation reference for decisions documented in Architecture (05).

Last Updated: 2026-05-25

4.3 KiB Raw Blame History