System Overview

🏗️ System Architecture

The API Server follows a strict Layered Architecture to ensure separation of concerns, testability, and code reuse across the Flutter ecosystem.

🧩 Dependency Injection

We use a Singleton pattern via AppDependencies (lib/src/config/app_dependencies.dart) to manage the lifecycle of all services.

• Initialization: Database connections and external clients are initialized once at startup.
• Access: Handlers access repositories via context.read<Repository>() (provided by Dart Frog middleware).

🧱 The Layers

1. Route Layer (routes/)

• Responsibility: Request parsing, validation, and response formatting.
• Logic: Minimal. Delegates immediately to Services or Repositories.
• Framework: Dart Frog.

2. Service Layer (lib/src/services/)

• Responsibility: Business logic that spans multiple data sources or requires orchestration.
• Examples:
  • AuthService: Coordinates User Repo, Token Service, and Email Service.
  • RewardsService: Coordinates User Rewards Repo, Idempotency Service, and AdMob Verifier.
  • AnalyticsSyncService: Orchestrates the ETL process between external providers and internal DB.

3. Repository Layer (packages/data_repository)

• Responsibility: Abstract data access. It provides a clean API for the application to interact with data, hiding the details of storage.
• Pattern: The API consumes the same shared repository package as the Flutter Mobile App. This ensures that business logic (like "how to fetch a headline") is consistent across platforms.

4. Data Client Layer (packages/data_mongodb)

• Responsibility: Low-level database interactions.
• Implementation: Uses mongo_dart to interact with the MongoDB database.
• Key Feature: Handles the translation between Dart's String id and MongoDB's ObjectId _id.

5. Shared Core (packages/core)

• Responsibility: Holds the "Source of Truth" for data models, enums, and exceptions.
• Usage: Used by the API, the Mobile App, and the Web Dashboard to ensure they all speak the same language.