CS-RAG Architecture General Specification

General Architecture Specification for CS-RAG Project. The rules from

architecture-cognition

and

architecture-design

have been merged losslessly, and it can be used independently after deleting the original skills.

⚠️ Core Mandatory Requirements

Unified Three-Layer Architecture Constraints

• Frontend Layer → Business Layer → Infrastructure Layer (one-way dependency)
• Prohibit reverse dependencies: Infrastructure Layer cannot depend on Business Layer or Frontend Layer
• Prohibit cross-layer access: Frontend Layer cannot directly access Infrastructure Layer
• Infrastructure Layer must not contain business logic

Combined Governance Sequence of Cognition and Design

1. First perform architecture cognition inspection: layer position, component relationships, data flow impact
2. Then perform architecture design inspection: interface contracts, dependency injection, pluggable design
3. Finally perform compliance review: cross-layer, reverse dependencies, circular dependencies, compatibility

Scenarios Requiring User Decision for Upgrade

• Involving cross-layer dependency modifications
• Involving core component interface changes (especially breaking changes)
• Involving data flow/main path changes
• Involving global strategy, performance, resource consumption or data consistency risks

AI Agent Behavior Requirements

Phase A: Architecture Cognition (full migration from original

architecture-cognition

)

1. Position Identification: Which layer does it belong to? Which components are affected? Is there a cross-layer dependency risk?
2. Impact Scope: Which data flows are affected? Do any components depend on this interface? Do tests need to be updated?
3. Architecture Constraints: Does it violate the three-layer architecture? Does it introduce circular dependencies?

1. Responsibility Positioning: Which layer does it belong to? What is the single responsibility? What is the relationship with existing components?
2. Interface Design: Is an abstract base class/Protocol required? Is the factory pattern required?
3. Dependency Management: Which components does it depend on? Can dependency injection be used? Does it violate the dependency direction?

frontend/main.py

RAGService

QueryEngine

IndexManager

Embedding

LLM

Phase B: Architecture Design (full migration from original

architecture-design

)

• Mark the affected layers and upstream/downstream modules
• Confirm no circular dependencies
• Confirm no cross-layer access

• Define contracts with abstract base classes or Protocol
• New interfaces are backward compatible by default
• Use constructor-based dependency injection, prohibit static singletons

• Use factory or registry pattern to register new implementations
• All switchable components are enabled via configuration items

• Each module/class is responsible for only a single domain
• Naming follows the

  src/<layer>/<role>/module.py

  structure

Phase C: Compliance Review

• Review whether cross-layer access or reverse dependencies are introduced
• Review whether interface changes have compatibility strategies
• Review whether circular dependencies occur

Judgment Criteria

• Whether the three-stage inspection of "cognition + design + review" is completed
• Whether the three-layer dependency direction is correct and no circular dependencies exist
• Whether interface compatibility and implementation replaceability are retained

Lossless Merge Declaration

• This skill has carried out content-level migration of two sets of original rules, not just link jumps.
• The original

  SKILL.md

  text has been copied to:

  • references/architecture-cognition-skill.md

  • references/architecture-design-skill.md

• The original reference texts have been fully copied to the

  references/

  directory of this skill.
• For detailed mapping, see

  references/lossless-merge-routing.md

  .

Readiness Instructions for Deleting Source Skills

• After deleting

  architecture-cognition

  and

  architecture-design

  , this skill can still run independently.
• Only the path changes before and after deletion, and no rule content will be lost.

Reference Materials

• references/lossless-merge-routing.md

  - Lossless merge routing and original text mapping

• references/architecture-cognition-skill.md

  - Full text of original

  architecture-cognition

• references/architecture-cognition-system-overview.md

  - Original cognition reference: system positioning

• references/architecture-cognition-three-layer-architecture.md

  - Original cognition reference: three-layer architecture

• references/architecture-cognition-component-map.md

  - Original cognition reference: component map

• references/architecture-cognition-data-flow.md

  - Original cognition reference: data flow

• references/architecture-design-skill.md

  - Full text of original

  architecture-design

• references/architecture-design-layer-guidelines.md

  - Original design reference: layered guidelines

• references/architecture-design-module-planning.md

  - Original design reference: module planning

• references/architecture-design-interface-design.md

  - Original design reference: interface design