Gosling2 Architecture Standards

NOTE: Core Architectural Laws (Strict Layering, God Object Ban, Service Bus) are enforced via rules/architecture.md.

This skill provides the detailed blueprints for implementing those laws.

1. The Layered Hierarchy (Detail)

1. •Presentation (UI): src/presentation/
   • •Can Import: Services (src/business).
   • •Cannot Import: Repositories (src/data).
   • •Forbidden: SQL, Business Orchestration.

Level 2: Business (Services)

• •Location: src/business/
• •Responsibility: Orchestration, Validation, Complex Calculation, Transaction Management.
• •Forbidden: PyQt widgets (signals/slots are okay), SQL.
• •Dependencies: Can import src/data (Repositories).

Level 3: Data (Repositories)

• •Location: src/data/
• •Responsibility: CRUD operations, SQL queries, DTO mapping.
• •Forbidden: Business Logic (e.g., "Calculate royalty"), UI code.
• •Dependencies: Can import src/core.

Level 4: Core (Shared)

• •Location: src/core/
• •Responsibility: Constants, Logging, Utilities, Exceptions.
• •Dependencies: None (Leaf nodes).

2. The Law of Modularization

• •God Object Ban: Any file exceeding 600 lines is considered a "God Object Risk".
• •Action: If you need to add code to a file > 600 lines, you must first propose a Split.
• •Splitting Strategy:
  • •UI: Split by visual component (e.g., SearchBar, FilterTree).
  • •Service: Split by domain (e.g., SongService vs PlaylistService).
  • •Utilities: Split by function (e.g., string_utils.py, file_utils.py).

3. The Service Bus Pattern

• •Communication: Sibling widgets (e.g., FilterTree vs Table) must NOT talk directly.
• •Mechanism: They communicate via LibraryService signals or a dedicated EventBus.

4. Resource Management

• •UI Styling: Strict ban on inline headers. Use theme.qss.
• •Strings: User-facing text should be centralizable (prepare for i18n).
• •Config: Hardcoded magic numbers belong in constants.py or settings.json.