# marcossevilla/compass_app architecture

> Architecture diagram of the GitHub repository marcossevilla/compass_app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marcossevilla/compass_app
- Repository: https://github.com/marcossevilla/compass_app

## Overview

##### Project Type & Purpose
- It is a full-stack Flutter application with a clearly separated mobile/desktop/web front-end (inside the “packages/app” package) and a backend server (located in “packages/api”) providing HTTP endpoints.
- The application lets users build and book travel itineraries, relying on several domain–specific packages (e.g., activity_repository, booking_repository, authentication_repository, etc.) and a shared models package.
- The project uses a monorepo structure (using Pub Workspaces) to isolate core functionalities, support multiple environments (development, staging, production), and promote high test coverage.

##### High-Level Architectural Components
a. Frontend (Flutter Application):
– Located in packages/app.
– Contains UI-related features such as login, home, activities, booking, search, and results.
– Uses Flutter state management (Cubit/bloc patterns) and routing (with a custom router package).
– Has multiple entry points (main_development.dart, main_staging.dart, main_production.dart) for different flavors.
– Integrates themes, localization, and custom widgets.

b. Backend (API Server):
– Found in packages/api.
– Built on Dart with shelf or dart_frog to simulate an HTTP server returning data.
– Exposes REST endpoints for bookings, login, continents, destinations, etc.
– Organizes its endpoints using a routes folder with middleware and specific route handlers.

c. Shared Domain & Data Layer:
– Several packages (activity_repository, booking_repository, authentication_repository, continent_repository, destination_repository, itinerary_config_repository, user_repository) encapsulate domain-specific logic.
– The models package contains the data models used across both frontend and backend.
– The api_client package is used by the Flutter app to communicate with the API server.

##### Relationships & Data Flow
- Users interact with the Flutter frontend, which, through its routing and state management layers (blocs and cubits), triggers use cases from various feature modules (login, booking, home, etc.).
- The Flutter app communicates with the API server via the api_client package. This connection represents the HTTP data flow from app (user device) to the backend server.
- On the backend, the API server uses route middleware to direct requests to the correct endpoints. These endpoints then utilize the various repository packages and models to fetch and return data.
- There is clear separation between UI (Flutter app), business logic (cubit/bloc and use cases), and data layers (repositories and API interaction).

##### Architectural Patterns & Design Principles
- It follows an opinionated “Very Good Architecture” for Flutter that cleanly separates concerns (presentation, domain, data) while maintaining modularity in a monorepo.
- Repositories and models are encapsulated in separate packages, ensuring that the same domain logic can be shared (or tested) independently.
- The project leverages dependency injection (implicitly via package inter-dependencies) and uses environment flavors to support different configurations.
- In the API server, middleware and route-based organization demonstrate a clean separation of concerns.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global node for user
    U("User"):::external

    %% Frontend Subgraph
    subgraph "Frontend (Flutter App)"
        FApp("Flutter Application"):::frontend
        %% Environment Entry Points Subgraph
        subgraph "Environment Entry Points"
            FDev("Entry Point (Development)"):::ui
            FStaging("Entry Point (Staging)"):::ui
            FProd("Entry Point (Production)"):::ui
        end
        %% UI Modules Subgraph
        subgraph "UI Modules"
            Login("Login Module"):::ui
            Home("Home Module"):::ui
            Activities("Activities Module"):::ui
            Booking("Booking Module"):::ui
            Search("Search Module"):::ui
            Results("Results Module"):::ui
        end
        SM("State Management (Cubit/Bloc)"):::logic
        Router("Routing"):::logic
        APIClient("API Client"):::logic
    end

    %% Backend Subgraph
    subgraph "Backend (API Server)"
        API("API Server"):::backend
        CoreLogic("Core API Logic"):::backend
        Routes("Routes & Middleware"):::backend
    end

    %% Shared Domain & Data Layer Subgraph
    subgraph "Shared Domain & Data"
        Models("Shared Models"):::shared
        subgraph "Repositories"
            ActivityRepo("Activity Repository"):::shared
            BookingRepo("Booking Repository"):::shared
            AuthRepo("Authentication Repository"):::shared
            ContinentRepo("Continent Repository"):::shared
            DestinationRepo("Destination Repository"):::shared
            ItineraryRepo("Itinerary Config Repository"):::shared
            UserRepo("User Repository"):::shared
        end
    end

    %% Relationships
    U -->|"initiates"| FApp
    FApp --> FDev
    FApp --> FStaging
    FApp --> FProd
    FApp --> Login
    FApp --> Home
    FApp --> Activities
    FApp --> Booking
    FApp --> Search
    FApp --> Results
    FApp --> SM
    FApp --> Router
    FApp --> APIClient

    APIClient -->|"HTTP_call"| API
    API --> CoreLogic
    API --> Routes
    Routes -->|"calls_repo"| ActivityRepo
    Routes -->|"calls_repo"| BookingRepo
    Routes -->|"calls_repo"| AuthRepo
    Routes -->|"calls_repo"| ContinentRepo
    Routes -->|"calls_repo"| DestinationRepo
    Routes -->|"calls_repo"| ItineraryRepo
    Routes -->|"calls_repo"| UserRepo
    APIClient -->|"serializes"| Models

    %% Click Events for Frontend
    click FApp "https://github.com/marcossevilla/compass_app/tree/main/packages/app"
    click FDev "https://github.com/marcossevilla/compass_app/blob/main/packages/app/lib/main_development.dart"
    click FStaging "https://github.com/marcossevilla/compass_app/blob/main/packages/app/lib/main_staging.dart"
    click FProd "https://github.com/marcossevilla/compass_app/blob/main/packages/app/lib/main_production.dart"
    click Login "https://github.com/marcossevilla/compass_app/tree/main/packages/app/lib/login"
    click Home "https://github.com/marcossevilla/compass_app/tree/main/packages/app/lib/home"
    click Activities "https://github.com/marcossevilla/compass_app/tree/main/packages/app/lib/activities"
    click Booking "https://github.com/marcossevilla/compass_app/tree/main/packages/app/lib/booking"
    click Search "https://github.com/marcossevilla/compass_app/tree/main/packages/app/lib/search_form"
    click Results "https://github.com/marcossevilla/compass_app/tree/main/packages/app/lib/results"
    click Router "https://github.com/marcossevilla/compass_app/tree/main/packages/app/lib/routing"
    click SM "https://github.com/marcossevilla/compass_app/tree/main/packages/app/lib/login/cubit"
    click APIClient "https://github.com/marcossevilla/compass_app/tree/main/packages/api_client"

    %% Click Events for Backend
    click API "https://github.com/marcossevilla/compass_app/tree/main/packages/api"
    click CoreLogic "https://github.com/marcossevilla/compass_app/blob/main/packages/api/lib/api.dart"
    click Routes "https://github.com/marcossevilla/compass_app/tree/main/packages/api/routes"

    %% Click Events for Shared Domain & Data
    click Models "https://github.com/marcossevilla/compass_app/tree/main/packages/models"
    click ActivityRepo "https://github.com/marcossevilla/compass_app/tree/main/packages/activity_repository"
    click BookingRepo "https://github.com/marcossevilla/compass_app/tree/main/packages/booking_repository"
    click AuthRepo "https://github.com/marcossevilla/compass_app/tree/main/packages/authentication_repository"
    click ContinentRepo "https://github.com/marcossevilla/compass_app/tree/main/packages/continent_repository"
    click DestinationRepo "https://github.com/marcossevilla/compass_app/tree/main/packages/destination_repository"
    click ItineraryRepo "https://github.com/marcossevilla/compass_app/tree/main/packages/itinerary_config_repository"
    click UserRepo "https://github.com/marcossevilla/compass_app/tree/main/packages/user_repository"

    %% Styles
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef frontend fill:#cce5ff,stroke:#0275d8,stroke-width:2px;
    classDef ui fill:#f8d7da,stroke:#d9534f,stroke-width:2px;
    classDef logic fill:#d1ecf1,stroke:#31708f,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#5cb85c,stroke-width:2px;
    classDef shared fill:#fff3cd,stroke:#f0ad4e,stroke-width:2px;
```
