mirror of
https://github.com/otaviocc/Triton.git
synced 2026-01-30 04:04:27 +00:00
98 lines
5.8 KiB
Markdown
98 lines
5.8 KiB
Markdown
# Architecture Decision Records (ADRs)
|
|
|
|
This directory contains Architecture Decision Records for the OMG application. These documents capture important architectural decisions, their context, and consequences.
|
|
|
|
## What is an ADR?
|
|
|
|
An Architecture Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences. This helps understand why certain decisions were made and provides guidance for future development.
|
|
|
|
## ADR Format
|
|
|
|
Each ADR follows this structure:
|
|
|
|
- **Status:** Accepted, Proposed, Deprecated, or Superseded
|
|
- **Date:** When the decision was made
|
|
- **Context:** The situation and requirements that led to the decision
|
|
- **Decision:** What was decided and key principles
|
|
- **Consequences:** Positive, negative, and neutral outcomes
|
|
- **Related Decisions:** Links to related ADRs
|
|
- **Notes:** Additional context or implementation details
|
|
|
|
## Core Architecture ADRs
|
|
|
|
### [ADR-001: Modular Architecture with Swift Package Manager](ADR-001-modular-architecture-with-spm.md)
|
|
Decision to use Swift Package Manager for modularizing the codebase into discrete, maintainable packages with clear dependency boundaries.
|
|
|
|
### [ADR-002: Layered Architecture and Dependency Direction](ADR-002-layered-architecture-and-dependency-direction.md)
|
|
Establishes the strict layered architecture with one-way dependency flow from Views → ViewModels → Repositories → Services → Foundation Modules.
|
|
|
|
### [ADR-003: Feature-Based Package Organization](ADR-003-feature-based-package-organization.md)
|
|
Defines how features are organized as complete vertical slices with their own layers, and how they integrate with the main application through AppFactory patterns.
|
|
|
|
## Technology Decisions
|
|
|
|
### [ADR-004: Migration from Combine to Async/Await](ADR-004-migration-from-combine-to-async-await.md)
|
|
Migration from Combine to async/await in services and repositories for cleaner asynchronous code and better integration with modern Swift concurrency.
|
|
|
|
### [ADR-005: Adoption of Swift Observation Framework](ADR-005-adoption-of-swift-observation-framework.md)
|
|
Adoption of Swift's @Observable macro to replace ObservableObject and @Published in view models, completing the removal of Combine from the UI layer.
|
|
|
|
### [ADR-006: Swift Data over Core Data](ADR-006-swift-data-over-core-data.md)
|
|
Migration from Core Data to Swift Data to eliminate excessive boilerplate for the application's straightforward data models.
|
|
|
|
### [ADR-007: MicroClient for HTTP Communication](ADR-007-microclient-for-http-communication.md)
|
|
Use of MicroClient, a custom-built lightweight HTTP client, for all API communication with type-safe request/response patterns.
|
|
|
|
### [ADR-008: MicroContainer for Dependency Injection](ADR-008-microcontainer-for-dependency-injection.md)
|
|
Use of MicroContainer (DependencyContainer), a custom-built lightweight DI container, for managing dependencies and factory registration throughout the application.
|
|
|
|
## Design Patterns
|
|
|
|
### [ADR-009: Protocol-First Repository and Service Boundaries](ADR-009-protocol-first-repository-and-service-boundaries.md)
|
|
Use of public protocols to define repository and service contracts, with Sendable conformance for concurrency safety. Only protocols are documented; implementations remain internal.
|
|
|
|
### [ADR-010: AppFactory Pattern for Feature Integration](ADR-010-appfactory-pattern-for-feature-integration.md)
|
|
Standardized factory pattern for feature integration with makeAppView(), makeScene(), and makeSettingsView() methods providing consistent entry points for all features.
|
|
|
|
### [ADR-011: Actor Isolation for Repository and Service Concurrency](ADR-011-actor-isolation-for-repository-concurrency.md)
|
|
Use of Swift actors for services and repositories to ensure thread safety and prevent data races while maintaining clean async/await APIs.
|
|
|
|
## Data Flow
|
|
|
|
### [ADR-012: DTO-Based Data Flow](ADR-012-dto-based-data-flow.md)
|
|
Use of Data Transfer Objects (DTOs) in the OMGAPI package to represent API contracts, with repositories responsible for mapping DTOs to domain models or persistence models.
|
|
|
|
### [ADR-013: Repository Caching and Streaming Patterns](ADR-013-repository-caching-and-streaming-patterns.md)
|
|
Stream-based caching pattern where repositories use AsyncStream to coordinate automatic data synchronization between network and SwiftData persistence layers.
|
|
|
|
## UI/UX Patterns
|
|
|
|
### [ADR-014: SwiftUI-First UI Development](ADR-014-swiftui-first-ui-development.md)
|
|
Pure SwiftUI approach for all UI development with no AppKit or UIKit usage, leveraging the DesignSystem package for shared components and consistent styling.
|
|
|
|
### [ADR-015: Context Menu Sharing Patterns](ADR-015-context-menu-sharing-patterns.md)
|
|
Standardized context menu structure for content items using native ShareLink for external sharing, with consistent ordering of edit, copy, share, and delete actions.
|
|
|
|
### [ADR-016: SwiftUI Previews with Mother Objects](ADR-016-swiftui-previews-with-mother-objects.md)
|
|
Use of Mother Object pattern for creating reusable test fixtures that support SwiftUI Previews across 90% of views, enabling rapid UI development with realistic data.
|
|
|
|
## Distribution
|
|
|
|
### [ADR-017: Direct Distribution Outside App Store](ADR-017-direct-distribution-outside-app-store.md)
|
|
Decision to distribute the application directly through downloadable installers outside the Mac App Store, prioritizing development velocity and cost efficiency while maintaining security through code signing and notarization.
|
|
|
|
## Contributing
|
|
|
|
When making significant architectural decisions:
|
|
|
|
1. Create a new ADR using the next available number
|
|
2. Follow the established format
|
|
3. Link to related ADRs
|
|
4. Update this README with the new ADR
|
|
|
|
## Status Definitions
|
|
|
|
- **Proposed:** Decision under consideration
|
|
- **Accepted:** Decision is approved and implemented
|
|
- **Deprecated:** No longer recommended but not yet removed
|
|
- **Superseded:** Replaced by another ADR (link to replacement)
|