refactor: update architecture documentation and add commenting standards

2026-09-05 19:40:35 +03:00
parent a55ee10d2b
commit ead0eecbc5
8 changed files with 331 additions and 3 deletions
@@ -0,0 +1,46 @@
+# ADR 0005: Strict Clean Architecture and Capability Modules
+
+## Context
+
+Mastermind is a complex macOS application with multiple responsibilities: continuous capture, knowledge extraction, local graph management, and AI assistance. To ensure maintainability, testability, and clear ownership of privacy boundaries, we need a robust architectural structure.
+
+## Decision
+
+We adopt a **Strict Clean Architecture** organized around **Capability Modules**.
+
+### 1. Capability Modules
+
+The codebase is divided into stable capability boundaries:
+
+- **AppShell**: Orchestration, lifecycle, and composition root.
+- **Observation**: Collectors and raw evidence acquisition.
+- **Knowledge**: The Context Graph, projection, and retrieval logic.
+- **Assistant**: AI sessions, provider routing, and prompt management.
+- **Trust**: Activity logging, health monitoring, and privacy enforcement.
+- **Infrastructure**: Shared utilities, encryption, and low-level storage.
+
+### 2. Strict Clean Architecture
+
+Each module follows Clean Architecture principles:
+
+- **Entities**: Pure domain models and logic (inner-most).
+- **Use Cases/Services**: Application-specific business rules.
+- **Interface Adapters**: Controllers, presenters, and gatekeepers.
+- **Frameworks & Drivers**: External tools like ScreenCaptureKit, SQLite, and sidecar clients (outer-most).
+
+### 3. Compile-Time Dependency Rule
+
+- Dependencies flow **inwards**: outer layers depend on inner layers.
+- Modules communicate through **Application Ports** (protocols).
+- **Protocols are required** at module boundaries and for all I/O (adapters).
+- Internal module logic does not require protocols for every internal function or value type, avoiding unnecessary boilerplate.
+
+### 4. Enforcement
+
+- Boundaries are enforced by separate Swift targets/modules where possible.
+- The **Composition Root** (in AppShell) is the only place where concrete adapters are instantiated and injected.
+
+## Consequences
+
+- **Pros**: Clearer boundaries, easier to mock dependencies for testing, better isolation of sensitive data processing, and independent evolution of capabilities.
+- **Cons**: Higher initial setup cost for new modules and mandatory boilerplate for cross-module communication.