# yonko-sid/quantsync_website architecture

> Architecture diagram of the GitHub repository yonko-sid/quantsync_website, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yonko-sid/quantsync_website
- Repository: https://github.com/yonko-sid/quantsync_website

## Overview

#### Purpose and Entry Points
QuantSync is a Flutter multi-platform client presenting an institutional crypto advisory and algorithmic-trading product suite. The implemented repository appears primarily to be a marketing/home experience with authentication/access UI and a dashboard route, rather than the exchange-ingestion or execution backend described in the README.

Flutter starts at `lib/main.dart`, which composes the application root in `lib/src/app.dart`. Native launchers host the same Flutter runtime on Android (`android/app/src/main/kotlin/com/example/quantsync/MainActivity.kt`), iOS (`ios/Runner/AppDelegate.swift`), desktop, and web (`web/index.html`).

#### Application Shell and Design System
`lib/src/app.dart` is the likely composition boundary for routing, theme selection, and top-level providers. Shared visual primitives are centralized in `lib/src/config/styles/app_themes.dart`, `lib/src/config/styles/app_colors.dart`, and `lib/src/config/styles/app_spacing.dart`; feature UI should consume these rather than define independent styling systems.

#### Home Experience and Navigation
The home feature organizes the public product experience. `lib/src/features/home/screens/home_screen.dart` likely owns the page-level layout/navigation, while `lib/src/features/home/screens/sections/header_section.dart` and `lib/src/features/home/screens/sections/hero_section.dart` establish the primary entry actions. Product and platform messaging is decomposed into independently composable sections such as `lib/src/features/home/screens/sections/products_showcase_section.dart` and `lib/src/features/home/screens/sections/integrations_section.dart`.

Interactive branding/visualization is isolated in `lib/src/features/home/widgets/hero_3d_graphic.dart`; the standalone `infinity-animation_3d.html` may support or prototype this presentation asset.

#### Authentication and Access Boundary
Authentication UI is separated from home content through `lib/src/features/auth/widgets/auth_modal.dart` and `lib/src/features/home/widgets/access_modal.dart`. Their backend boundary is `lib/src/repositories/auth_repository.dart`, with session/auth state exposed via `lib/src/state/auth_provider.dart`. This separation permits demo-mode UI when backend configuration is unavailable and keeps Supabase calls out of presentation components.

#### Backend, Runtime State, and Product Services
Supabase is the declared external backend and is encapsulated by `lib/src/services/supabase_service.dart`. Its URL and anonymous key are supplied at runtime using Dart defines; absent configuration should preserve demo behavior rather than fail application startup.

Cross-cutting client state is partitioned by concern: `lib/src/state/app_state_provider.dart` for app-wide state, `lib/src/state/theme_provider.dart` for appearance, and `lib/src/state/device_info_provider.dart` for platform/device adaptation. Service boundaries include analytics (`lib/src/services/analytics_service.dart`), remotely controlled capability decisions (`lib/src/services/feature_flag_service.dart`), and downloads (`lib/src/service/download_service.dart`).

#### Dashboard and Domain Presentation
Authenticated or product-facing dashboard UI resides in `lib/src/features/home/screens/dashboard_screen.dart`. Domain display data is modeled independently in `lib/src/models/product_model.dart`, allowing product showcase/dashboard components to render structured product metadata without coupling to transport or authentication concerns.

#### Deployment Surface
The primary documented runtime is Flutter Web on Chrome/Chromium, hosted from `web/index.html` with web metadata in `web/manifest.json`. The repository also ships Flutter-generated platform hosts for Android, iOS, macOS, Linux, and Windows, making the Dart application layer portable while platform-specific build and launch responsibilities remain under their respective top-level directories.

Main entry points: [`lib/src/app.dart`](https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/app.dart) (App shell), [`lib/src/features/home/screens/home_screen.dart`](https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/features/home/screens/home_screen.dart) (Home screen), [`lib/src/features/home/screens/sections/hero_section.dart`](https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/features/home/screens/sections/hero_section.dart) (Home sections), [`lib/src/features/home/screens/dashboard_screen.dart`](https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/features/home/screens/dashboard_screen.dart) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hosts["Platform Hosts"]
  node_flutter_runtime{{"Flutter runtime<br/>cross-platform client"}}
  node_android_host["Android launcher<br/>native host<br/>[MainActivity.kt]"]
  node_ios_host["iOS launcher<br/>native host<br/>[AppDelegate.swift]"]
  node_web_host["Web host<br/>web entry<br/>[index.html]"]
end

subgraph group_core["App Core"]
  node_main["Application entry<br/>Dart entrypoint<br/>[main.dart]"]
  node_app["App shell<br/>composition root<br/>[app.dart]"]
  node_design_system["Design system<br/>shared styles<br/>[app_themes.dart]"]
  node_client_state["Client state<br/>providers"]
end

subgraph group_home["Home &amp; Dashboard"]
  node_home_screen["Home screen<br/>page layout<br/>[home_screen.dart]"]
  node_home_sections["Home sections<br/>composable content<br/>[hero_section.dart]"]
  node_hero_graphic["Hero 3D graphic<br/>interactive visual"]
  node_dashboard["Dashboard<br/>product page"]
  node_product_model["Product model<br/>domain model<br/>[product_model.dart]"]
end

subgraph group_access["Access &amp; Backend"]
  node_access_ui["Access UI<br/>auth modals<br/>[auth_modal.dart]"]
  node_auth_state["Auth state<br/>state provider<br/>[auth_provider.dart]"]
  node_auth_repository["Auth repository"]
  node_supabase[("Supabase service<br/>backend adapter")]
end

subgraph group_services["Client Services"]
  node_product_services["Product services<br/>client services"]
end

node_android_host -->|"launches"| node_flutter_runtime
node_ios_host -->|"launches"| node_flutter_runtime
node_web_host -->|"hosts"| node_flutter_runtime
node_flutter_runtime -->|"starts"| node_main
node_main -->|"creates"| node_app
node_app -->|"provides"| node_client_state
node_app -->|"applies"| node_design_system
node_app -->|"routes to"| node_home_screen
node_app -->|"routes to"| node_dashboard
node_home_screen -->|"composes"| node_home_sections
node_home_sections -->|"embeds"| node_hero_graphic
node_home_sections -->|"opens"| node_access_ui
node_dashboard -->|"renders"| node_product_model
node_access_ui -->|"uses"| node_auth_state
node_auth_state -->|"delegates to"| node_auth_repository
node_auth_repository -->|"authenticates via"| node_supabase
node_app -.->|"initializes"| node_product_services
node_home_screen -->|"uses"| node_design_system
node_dashboard -->|"uses"| node_design_system

click node_android_host "https://github.com/yonko-sid/quantsync_website/blob/main/android/app/src/main/kotlin/com/example/quantsync/MainActivity.kt"
click node_ios_host "https://github.com/yonko-sid/quantsync_website/blob/main/ios/Runner/AppDelegate.swift"
click node_web_host "https://github.com/yonko-sid/quantsync_website/blob/main/web/index.html"
click node_main "https://github.com/yonko-sid/quantsync_website/blob/main/lib/main.dart"
click node_app "https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/app.dart"
click node_design_system "https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/config/styles/app_themes.dart"
click node_client_state "https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/state/app_state_provider.dart"
click node_home_screen "https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/features/home/screens/home_screen.dart"
click node_home_sections "https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/features/home/screens/sections/hero_section.dart"
click node_hero_graphic "https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/features/home/widgets/hero_3d_graphic.dart"
click node_dashboard "https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/features/home/screens/dashboard_screen.dart"
click node_product_model "https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/models/product_model.dart"
click node_access_ui "https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/features/auth/widgets/auth_modal.dart"
click node_auth_state "https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/state/auth_provider.dart"
click node_auth_repository "https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/repositories/auth_repository.dart"
click node_supabase "https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/services/supabase_service.dart"
click node_product_services "https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/services/analytics_service.dart"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flutter_runtime,node_android_host,node_ios_host,node_web_host toneBlue
class node_main,node_app,node_design_system,node_client_state toneAmber
class node_home_screen,node_home_sections,node_hero_graphic,node_dashboard,node_product_model toneMint
class node_access_ui,node_auth_state,node_auth_repository,node_supabase toneRose
class node_product_services toneIndigo
```

## Components

### Platform Hosts

Native and web launch surfaces for the Flutter runtime.

- **Flutter runtime**: cross-platform client
- [Android launcher](https://github.com/yonko-sid/quantsync_website/blob/main/android/app/src/main/kotlin/com/example/quantsync/MainActivity.kt): native host · `android/app/src/main/kotlin/com/example/quantsync/MainActivity.kt`
- [iOS launcher](https://github.com/yonko-sid/quantsync_website/blob/main/ios/Runner/AppDelegate.swift): native host · `ios/Runner/AppDelegate.swift`
- [Web host](https://github.com/yonko-sid/quantsync_website/blob/main/web/index.html): web entry · `web/index.html`

### App Core

Application composition, styling, and cross-cutting state.

- [Application entry](https://github.com/yonko-sid/quantsync_website/blob/main/lib/main.dart): Dart entrypoint · `lib/main.dart`
- [App shell](https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/app.dart): composition root · Composes routing, theme, and top-level providers. · `lib/src/app.dart`
- [Design system](https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/config/styles/app_themes.dart): shared styles · Themes, colors, and spacing primitives. · `lib/src/config/styles/app_themes.dart`
- [Client state](https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/state/app_state_provider.dart): providers · App-wide, theme, and device adaptation state. · `lib/src/state/app_state_provider.dart`

### Home & Dashboard

Public product experience and authenticated product views.

- [Home screen](https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/features/home/screens/home_screen.dart): page layout · `lib/src/features/home/screens/home_screen.dart`
- [Home sections](https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/features/home/screens/sections/hero_section.dart): composable content · Header, hero, product showcase, and integration messaging. · `lib/src/features/home/screens/sections/hero_section.dart`
- [Hero 3D graphic](https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/features/home/widgets/hero_3d_graphic.dart): interactive visual · `lib/src/features/home/widgets/hero_3d_graphic.dart`
- [Dashboard](https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/features/home/screens/dashboard_screen.dart): product page · `lib/src/features/home/screens/dashboard_screen.dart`
- [Product model](https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/models/product_model.dart): domain model · Structured product metadata for presentation. · `lib/src/models/product_model.dart`

### Access & Backend

Authentication boundary and external backend integration.

- [Access UI](https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/features/auth/widgets/auth_modal.dart): auth modals · Authentication and home access presentation boundary. · `lib/src/features/auth/widgets/auth_modal.dart`
- [Auth state](https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/state/auth_provider.dart): state provider · `lib/src/state/auth_provider.dart`
- [Auth repository](https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/repositories/auth_repository.dart): repository · Keeps backend calls out of presentation components. · `lib/src/repositories/auth_repository.dart`
- [Supabase service](https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/services/supabase_service.dart): backend adapter · Uses runtime Dart defines and supports demo mode without configuration. · `lib/src/services/supabase_service.dart`

### Client Services

Cross-cutting product capability services.

- [Product services](https://github.com/yonko-sid/quantsync_website/blob/main/lib/src/services/analytics_service.dart): client services · Analytics, feature flags, and download capabilities. · `lib/src/services/analytics_service.dart`

## Connections

- Android launcher → Flutter runtime: launches
- iOS launcher → Flutter runtime: launches
- Web host → Flutter runtime: hosts
- Flutter runtime → Application entry: starts
- Application entry → App shell: creates
- App shell → Client state: provides
- App shell → Design system: applies
- App shell → Home screen: routes to
- App shell → Dashboard: routes to
- Home screen → Home sections: composes
- Home sections → Hero 3D graphic: embeds
- Home sections → Access UI: opens
- Dashboard → Product model: renders
- Access UI → Auth state: uses
- Auth state → Auth repository: delegates to
- Auth repository → Supabase service: authenticates via
- App shell → Product services: initializes
- Home screen → Design system: uses
- Dashboard → Design system: uses