How marcossevilla/compass_app works
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.