# felipedenuzzo/vigilway architecture

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

- Interactive diagram: https://gitdiagram.com/felipedenuzzo/vigilway
- Repository: https://github.com/felipedenuzzo/vigilway

## Overview

VigilWay is a browser-based cognitive-training journey: a user signs in or continues as a guest, chooses a guided training step, completes an exercise, and the app resolves progress, lives, and journey state. Evidence sampled shows the app-level orchestration, journey/life rules, one training implementation, and offline-first journey persistence; the tree lists additional training modules and UI capabilities whose internal wiring was not sampled, so those links are limited to documented registry and app entry points where supported.

Main entry points: [`src/App.tsx`](https://github.com/felipedenuzzo/vigilway/blob/main/src/App.tsx) (Application controller), [`src/services/adminNotesService.ts`](https://github.com/felipedenuzzo/vigilway/blob/main/src/services/adminNotesService.ts) (Admin notes service), [`src/core/storage/localStorageAdapter.ts`](https://github.com/felipedenuzzo/vigilway/blob/main/src/core/storage/localStorageAdapter.ts) (Local journey storage), [`src/core/firebase/firebaseClient.ts`](https://github.com/felipedenuzzo/vigilway/blob/main/src/core/firebase/firebaseClient.ts) (Firebase client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_journey["Journey and play"]
  node_app["Application controller<br/>[App.tsx]"]
  node_home["Journey home"]
  node_runner["Game runner<br/>[GameRunner.tsx]"]
  node_transition["Transition screen"]
  node_journey_rules["Journey progression<br/>[journeyManager.ts]"]
  node_life_rules["Lives and challenge<br/>[lifeManager.ts]"]
  node_celebration["Item celebration"]
end

subgraph group_training["Training activities"]
  node_training_registry["Training registry"]
  node_training_instructions["Training instructions"]
  node_visual_search["Visual search exercise"]
  node_other_trainings["Other exercises"]
  node_risk_challenge["Risk-all challenge"]
end

subgraph group_identity["Identity and persistence"]
  node_auth_ui["Sign-in modal<br/>[AuthModal.tsx]"]
  node_auth["Authentication context<br/>[AuthContext.tsx]"]
  node_firebase_client["Firebase client<br/>[firebaseClient.ts]"]
  node_storage["Local journey storage"]
  node_firestore_sync["Firestore journey sync<br/>[firestoreSync.ts]"]
end

subgraph group_insight_admin["Insights and admin"]
  node_insight["Cognitive insight"]
  node_admin_notes["Admin notes service"]
  node_admin_ui["Inspector and feedback<br/>[InspectorPanel.tsx]"]
end

node_learner(("Learner"))
node_firebase_auth_service[("Firebase Authentication")]
node_firestore[("Cloud Firestore")]
node_local_browser[("Browser local storage")]
node_gemini_endpoint(("Configured insight endpoint"))

node_learner -->|"signs in"| node_auth_ui
node_auth_ui -->|"requests auth"| node_auth
node_auth -->|"gets client"| node_firebase_client
node_firebase_client -->|"authenticates"| node_firebase_auth_service
node_learner -->|"chooses activity"| node_home
node_app -->|"reads session"| node_auth
node_app -->|"loads journey"| node_storage
node_storage -->|"fetches and syncs"| node_firestore_sync
node_storage -->|"reads and writes"| node_local_browser
node_firestore_sync -->|"gets client"| node_firebase_client
node_firestore_sync -->|"syncs journey"| node_firestore
node_app -->|"renders"| node_home
node_home -->|"starts session"| node_app
node_app -->|"selects next attention"| node_journey_rules
node_app -->|"selects training"| node_training_registry
node_app -->|"shows transition"| node_transition
node_app -->|"renders session"| node_runner
node_training_registry -->|"resolves module"| node_visual_search
node_visual_search -->|"returns result"| node_runner
node_visual_search -.->|"uses guidance"| node_training_instructions
node_app -->|"resolves outcome"| node_journey_rules
node_journey_rules -->|"updates lives"| node_life_rules
node_app -->|"saves progress"| node_storage
node_app -.->|"shows milestone"| node_celebration
node_app -.->|"offers challenge"| node_risk_challenge
node_risk_challenge -.->|"reports outcome"| node_app
node_app -.->|"offers activities"| node_other_trainings
node_app -.->|"requests item insight"| node_insight
node_insight -.->|"enriches insight"| node_gemini_endpoint
node_admin_ui -.->|"manages notes"| node_admin_notes
node_admin_notes -->|"caches notes"| node_local_browser
node_admin_notes -->|"gets client"| node_firebase_client
node_admin_notes -->|"stores notes"| node_firestore

click node_app "https://github.com/felipedenuzzo/vigilway/blob/main/src/App.tsx"
click node_home "https://github.com/felipedenuzzo/vigilway/blob/main/src/features/home/JourneyHomeScreen.tsx"
click node_runner "https://github.com/felipedenuzzo/vigilway/blob/main/src/runner/GameRunner.tsx"
click node_transition "https://github.com/felipedenuzzo/vigilway/blob/main/src/runner/TransitionScreen.tsx"
click node_journey_rules "https://github.com/felipedenuzzo/vigilway/blob/main/src/journey/journeyManager.ts"
click node_life_rules "https://github.com/felipedenuzzo/vigilway/blob/main/src/journey/lifeManager.ts"
click node_celebration "https://github.com/felipedenuzzo/vigilway/blob/main/src/journey/ItemCelebrationModal.tsx"
click node_training_registry "https://github.com/felipedenuzzo/vigilway/blob/main/src/trainings/trainingRegistry.ts"
click node_training_instructions "https://github.com/felipedenuzzo/vigilway/blob/main/src/trainings/trainingInstructions.ts"
click node_visual_search "https://github.com/felipedenuzzo/vigilway/blob/main/src/trainings/visual-search/VisualSearchModule.tsx"
click node_other_trainings "https://github.com/felipedenuzzo/vigilway/tree/main/src/trainings"
click node_risk_challenge "https://github.com/felipedenuzzo/vigilway/blob/main/src/features/challenge/RiskAllChallengeModal.tsx"
click node_auth_ui "https://github.com/felipedenuzzo/vigilway/blob/main/src/components/auth/AuthModal.tsx"
click node_auth "https://github.com/felipedenuzzo/vigilway/blob/main/src/core/auth/AuthContext.tsx"
click node_firebase_client "https://github.com/felipedenuzzo/vigilway/blob/main/src/core/firebase/firebaseClient.ts"
click node_storage "https://github.com/felipedenuzzo/vigilway/blob/main/src/core/storage/localStorageAdapter.ts"
click node_firestore_sync "https://github.com/felipedenuzzo/vigilway/blob/main/src/core/firebase/firestoreSync.ts"
click node_insight "https://github.com/felipedenuzzo/vigilway/blob/main/src/services/aiInsightService.ts"
click node_admin_notes "https://github.com/felipedenuzzo/vigilway/blob/main/src/services/adminNotesService.ts"
click node_admin_ui "https://github.com/felipedenuzzo/vigilway/blob/main/src/runner/InspectorPanel.tsx"

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_app,node_home,node_runner,node_transition,node_journey_rules,node_life_rules,node_celebration toneBlue
class node_training_registry,node_training_instructions,node_visual_search,node_other_trainings,node_risk_challenge,node_firebase_auth_service,node_firestore,node_local_browser toneAmber
class node_auth_ui,node_auth,node_firebase_client,node_storage,node_firestore_sync toneMint
class node_insight,node_admin_notes,node_admin_ui toneRose
class node_learner,node_gemini_endpoint toneIndigo
```

## Components

### Journey and play

- [Application controller](https://github.com/felipedenuzzo/vigilway/blob/main/src/App.tsx): `src/App.tsx`
- [Journey home](https://github.com/felipedenuzzo/vigilway/blob/main/src/features/home/JourneyHomeScreen.tsx): `src/features/home/JourneyHomeScreen.tsx`
- [Game runner](https://github.com/felipedenuzzo/vigilway/blob/main/src/runner/GameRunner.tsx): `src/runner/GameRunner.tsx`
- [Transition screen](https://github.com/felipedenuzzo/vigilway/blob/main/src/runner/TransitionScreen.tsx): `src/runner/TransitionScreen.tsx`
- [Journey progression](https://github.com/felipedenuzzo/vigilway/blob/main/src/journey/journeyManager.ts): `src/journey/journeyManager.ts`
- [Lives and challenge](https://github.com/felipedenuzzo/vigilway/blob/main/src/journey/lifeManager.ts): `src/journey/lifeManager.ts`
- [Item celebration](https://github.com/felipedenuzzo/vigilway/blob/main/src/journey/ItemCelebrationModal.tsx): `src/journey/ItemCelebrationModal.tsx`

### Training activities

- [Training registry](https://github.com/felipedenuzzo/vigilway/blob/main/src/trainings/trainingRegistry.ts): `src/trainings/trainingRegistry.ts`
- [Training instructions](https://github.com/felipedenuzzo/vigilway/blob/main/src/trainings/trainingInstructions.ts): `src/trainings/trainingInstructions.ts`
- [Visual search exercise](https://github.com/felipedenuzzo/vigilway/blob/main/src/trainings/visual-search/VisualSearchModule.tsx): `src/trainings/visual-search/VisualSearchModule.tsx`
- [Other exercises](https://github.com/felipedenuzzo/vigilway/tree/main/src/trainings): `src/trainings`
- [Risk-all challenge](https://github.com/felipedenuzzo/vigilway/blob/main/src/features/challenge/RiskAllChallengeModal.tsx): `src/features/challenge/RiskAllChallengeModal.tsx`

### Identity and persistence

- [Sign-in modal](https://github.com/felipedenuzzo/vigilway/blob/main/src/components/auth/AuthModal.tsx): `src/components/auth/AuthModal.tsx`
- [Authentication context](https://github.com/felipedenuzzo/vigilway/blob/main/src/core/auth/AuthContext.tsx): `src/core/auth/AuthContext.tsx`
- [Firebase client](https://github.com/felipedenuzzo/vigilway/blob/main/src/core/firebase/firebaseClient.ts): `src/core/firebase/firebaseClient.ts`
- [Local journey storage](https://github.com/felipedenuzzo/vigilway/blob/main/src/core/storage/localStorageAdapter.ts): `src/core/storage/localStorageAdapter.ts`
- [Firestore journey sync](https://github.com/felipedenuzzo/vigilway/blob/main/src/core/firebase/firestoreSync.ts): `src/core/firebase/firestoreSync.ts`

### Insights and admin

- [Cognitive insight](https://github.com/felipedenuzzo/vigilway/blob/main/src/services/aiInsightService.ts): `src/services/aiInsightService.ts`
- [Admin notes service](https://github.com/felipedenuzzo/vigilway/blob/main/src/services/adminNotesService.ts): `src/services/adminNotesService.ts`
- [Inspector and feedback](https://github.com/felipedenuzzo/vigilway/blob/main/src/runner/InspectorPanel.tsx): `src/runner/InspectorPanel.tsx`

### Other components

- **Learner**
- **Firebase Authentication**
- **Cloud Firestore**
- **Browser local storage**
- **Configured insight endpoint**

## Connections

- Learner → Sign-in modal: signs in
- Sign-in modal → Authentication context: requests auth
- Authentication context → Firebase client: gets client
- Firebase client → Firebase Authentication: authenticates
- Learner → Journey home: chooses activity
- Application controller → Authentication context: reads session
- Application controller → Local journey storage: loads journey
- Local journey storage → Firestore journey sync: fetches and syncs
- Local journey storage → Browser local storage: reads and writes
- Firestore journey sync → Firebase client: gets client
- Firestore journey sync → Cloud Firestore: syncs journey
- Application controller → Journey home: renders
- Journey home → Application controller: starts session
- Application controller → Journey progression: selects next attention
- Application controller → Training registry: selects training
- Application controller → Transition screen: shows transition
- Application controller → Game runner: renders session
- Training registry → Visual search exercise: resolves module
- Visual search exercise → Game runner: returns result
- Visual search exercise → Training instructions: uses guidance
- Application controller → Journey progression: resolves outcome
- Journey progression → Lives and challenge: updates lives
- Application controller → Local journey storage: saves progress
- Application controller → Item celebration: shows milestone
- Application controller → Risk-all challenge: offers challenge
- Risk-all challenge → Application controller: reports outcome
- Application controller → Other exercises: offers activities
- Application controller → Cognitive insight: requests item insight
- Cognitive insight → Configured insight endpoint: enriches insight
- Inspector and feedback → Admin notes service: manages notes
- Admin notes service → Browser local storage: caches notes
- Admin notes service → Firebase client: gets client
- Admin notes service → Cloud Firestore: stores notes