Skip to content

README.md

Latest commit

 

History

History
107 lines (72 loc) · 4.31 KB

README.md

File metadata and controls

107 lines (72 loc) · 4.31 KB

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:

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

System Architects and Reviewers

Personnel focused on system integrity and long-term maintenance:

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

Operations and Release Engineers

Those managing the application lifecycle post-development:

  1. 12 Collaboration and Versioning — for release tags and branch management.
  2. 02 Tech Stack — for environment provisioning and dependency management.
  3. 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