# shadhin78/x-29-advance architecture

> Architecture diagram of the GitHub repository shadhin78/x-29-advance, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shadhin78/x-29-advance
- Repository: https://github.com/shadhin78/x-29-advance

## Overview

X-29 is a private academic execution workspace. The main flow is an administrator entering through authentication, using dashboard studios to plan and track study, and persisting changes locally with queued cloud sync. The graph retains the README’s major product domains; legacy archived code is excluded from the active architecture. Several feature routes, stores, and integrations are represented from documented capabilities and tree paths, since their source was not sampled; their uncertain connections are omitted.

Main entry points: [`stores/useTaskStore.ts`](https://github.com/shadhin78/x-29-advance/blob/main/stores/useTaskStore.ts) (Study tasks), [`features/dashboard/components/DashboardStudio.tsx`](https://github.com/shadhin78/x-29-advance/blob/main/features/dashboard/components/DashboardStudio.tsx) (Dashboard overview), [`lib/sync/syncService.ts`](https://github.com/shadhin78/x-29-advance/blob/main/lib/sync/syncService.ts) (Cloud sync queue), [`features/subjects/components/SubjectsStudio.tsx`](https://github.com/shadhin78/x-29-advance/blob/main/features/subjects/components/SubjectsStudio.tsx) (Subjects and syllabus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and shell"]
  node_login["Login<br/>[page.tsx]"]
  node_auth["Auth service<br/>[authService.ts]"]
  node_gate["Auth gate<br/>[AuthGate.tsx]"]
  node_shell["Dashboard shell<br/>[AppShell.tsx]"]
end

subgraph group_planning["Planning and syllabus"]
  node_config["Master config"]
  node_taxonomy["Taxonomy service<br/>[taxonomyService.ts]"]
  node_subjects["Subjects and syllabus<br/>[SubjectsStudio.tsx]"]
  node_targets["Target allocation"]
end

subgraph group_execution["Study execution"]
  node_actions["Daily actions"]
  node_tasks["Study tasks<br/>[useTaskStore.ts]"]
  node_schedule["Schedule matrix<br/>[ScheduleStudio.tsx]"]
  node_focus["Focus timer<br/>[timerEngine.ts]"]
  node_timerstore["Timer state<br/>[useTimerStore.ts]"]
  node_exams["Exam routine<br/>[examService.ts]"]
end

subgraph group_insight["Progress and outcomes"]
  node_home["Dashboard overview"]
  node_pace["Pace studio<br/>[paceEngine.ts]"]
  node_outcome["Outcome and CGPA<br/>[outcomeEngine.ts]"]
  node_analytics["Visual analytics"]
end

subgraph group_platform["Persistence and sync"]
  node_idb[("IndexedDB<br/>[indexeddb.ts]")]
  node_sync["Cloud sync queue<br/>[syncService.ts]"]
  node_firebase["Firebase services<br/>[client.ts]"]
  node_firestore[("Firestore<br/>[firestore.ts]")]
end

node_admin(("Administrator"))

node_admin -->|"signs in"| node_login
node_login -.->|"authenticates"| node_auth
node_auth -->|"uses auth"| node_firebase
node_gate -.->|"checks session"| node_auth
node_gate -.->|"opens workspace"| node_shell
node_shell -.->|"presents overview"| node_home
node_home -.->|"surfaces checklist"| node_actions
node_home -.->|"shows countdown"| node_exams
node_home -.->|"shows progress"| node_pace
node_config -.->|"edits taxonomy"| node_taxonomy
node_subjects -.->|"tracks chapters"| node_tasks
node_targets -.->|"allocates targets"| node_actions
node_actions -.->|"updates tasks"| node_tasks
node_schedule -.->|"allocates study time"| node_subjects
node_focus -.->|"computes timer state"| node_timerstore
node_tasks -->|"reads and writes"| node_idb
node_tasks -->|"queues changes"| node_sync
node_sync -->|"stores queue"| node_idb
node_sync -->|"checks current user"| node_firebase
node_sync -->|"writes patches"| node_firestore
node_pace -.->|"estimates velocity"| node_subjects
node_outcome -.->|"calculates results"| node_subjects
node_analytics -.->|"analyzes activity"| node_tasks

click node_login "https://github.com/shadhin78/x-29-advance/blob/main/app/login/page.tsx"
click node_auth "https://github.com/shadhin78/x-29-advance/blob/main/services/authService.ts"
click node_gate "https://github.com/shadhin78/x-29-advance/blob/main/components/auth/AuthGate.tsx"
click node_shell "https://github.com/shadhin78/x-29-advance/blob/main/components/shell/AppShell.tsx"
click node_home "https://github.com/shadhin78/x-29-advance/blob/main/features/dashboard/components/DashboardStudio.tsx"
click node_config "https://github.com/shadhin78/x-29-advance/blob/main/features/config/components/MasterConfigStudio.tsx"
click node_taxonomy "https://github.com/shadhin78/x-29-advance/blob/main/features/taxonomy/services/taxonomyService.ts"
click node_subjects "https://github.com/shadhin78/x-29-advance/blob/main/features/subjects/components/SubjectsStudio.tsx"
click node_targets "https://github.com/shadhin78/x-29-advance/blob/main/features/targets/services/targetAllocationEngine.ts"
click node_actions "https://github.com/shadhin78/x-29-advance/blob/main/features/daily-actions/components/DailyActionsStudio.tsx"
click node_tasks "https://github.com/shadhin78/x-29-advance/blob/main/stores/useTaskStore.ts"
click node_schedule "https://github.com/shadhin78/x-29-advance/blob/main/features/schedule/components/ScheduleStudio.tsx"
click node_focus "https://github.com/shadhin78/x-29-advance/blob/main/features/focus/services/timerEngine.ts"
click node_timerstore "https://github.com/shadhin78/x-29-advance/blob/main/stores/useTimerStore.ts"
click node_exams "https://github.com/shadhin78/x-29-advance/blob/main/features/exam/services/examService.ts"
click node_pace "https://github.com/shadhin78/x-29-advance/blob/main/features/pace/services/paceEngine.ts"
click node_outcome "https://github.com/shadhin78/x-29-advance/blob/main/features/outcome/services/outcomeEngine.ts"
click node_analytics "https://github.com/shadhin78/x-29-advance/blob/main/features/analytics/services/analyticsService.ts"
click node_idb "https://github.com/shadhin78/x-29-advance/blob/main/lib/storage/indexeddb.ts"
click node_sync "https://github.com/shadhin78/x-29-advance/blob/main/lib/sync/syncService.ts"
click node_firebase "https://github.com/shadhin78/x-29-advance/blob/main/lib/firebase/client.ts"
click node_firestore "https://github.com/shadhin78/x-29-advance/blob/main/lib/firebase/firestore.ts"

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_login,node_auth,node_gate,node_shell toneBlue
class node_config,node_taxonomy,node_subjects,node_targets toneAmber
class node_actions,node_tasks,node_schedule,node_focus,node_timerstore,node_exams toneMint
class node_home,node_pace,node_outcome,node_analytics toneRose
class node_idb,node_sync,node_firebase,node_firestore,node_admin toneIndigo
```

## Components

### Access and shell

- [Login](https://github.com/shadhin78/x-29-advance/blob/main/app/login/page.tsx): `app/login/page.tsx`
- [Auth service](https://github.com/shadhin78/x-29-advance/blob/main/services/authService.ts): `services/authService.ts`
- [Auth gate](https://github.com/shadhin78/x-29-advance/blob/main/components/auth/AuthGate.tsx): `components/auth/AuthGate.tsx`
- [Dashboard shell](https://github.com/shadhin78/x-29-advance/blob/main/components/shell/AppShell.tsx): `components/shell/AppShell.tsx`

### Planning and syllabus

- [Master config](https://github.com/shadhin78/x-29-advance/blob/main/features/config/components/MasterConfigStudio.tsx): `features/config/components/MasterConfigStudio.tsx`
- [Taxonomy service](https://github.com/shadhin78/x-29-advance/blob/main/features/taxonomy/services/taxonomyService.ts): `features/taxonomy/services/taxonomyService.ts`
- [Subjects and syllabus](https://github.com/shadhin78/x-29-advance/blob/main/features/subjects/components/SubjectsStudio.tsx): `features/subjects/components/SubjectsStudio.tsx`
- [Target allocation](https://github.com/shadhin78/x-29-advance/blob/main/features/targets/services/targetAllocationEngine.ts): `features/targets/services/targetAllocationEngine.ts`

### Study execution

- [Daily actions](https://github.com/shadhin78/x-29-advance/blob/main/features/daily-actions/components/DailyActionsStudio.tsx): `features/daily-actions/components/DailyActionsStudio.tsx`
- [Study tasks](https://github.com/shadhin78/x-29-advance/blob/main/stores/useTaskStore.ts): `stores/useTaskStore.ts`
- [Schedule matrix](https://github.com/shadhin78/x-29-advance/blob/main/features/schedule/components/ScheduleStudio.tsx): `features/schedule/components/ScheduleStudio.tsx`
- [Focus timer](https://github.com/shadhin78/x-29-advance/blob/main/features/focus/services/timerEngine.ts): `features/focus/services/timerEngine.ts`
- [Timer state](https://github.com/shadhin78/x-29-advance/blob/main/stores/useTimerStore.ts): `stores/useTimerStore.ts`
- [Exam routine](https://github.com/shadhin78/x-29-advance/blob/main/features/exam/services/examService.ts): `features/exam/services/examService.ts`

### Progress and outcomes

- [Dashboard overview](https://github.com/shadhin78/x-29-advance/blob/main/features/dashboard/components/DashboardStudio.tsx): `features/dashboard/components/DashboardStudio.tsx`
- [Pace studio](https://github.com/shadhin78/x-29-advance/blob/main/features/pace/services/paceEngine.ts): `features/pace/services/paceEngine.ts`
- [Outcome and CGPA](https://github.com/shadhin78/x-29-advance/blob/main/features/outcome/services/outcomeEngine.ts): `features/outcome/services/outcomeEngine.ts`
- [Visual analytics](https://github.com/shadhin78/x-29-advance/blob/main/features/analytics/services/analyticsService.ts): `features/analytics/services/analyticsService.ts`

### Persistence and sync

- [IndexedDB](https://github.com/shadhin78/x-29-advance/blob/main/lib/storage/indexeddb.ts): `lib/storage/indexeddb.ts`
- [Cloud sync queue](https://github.com/shadhin78/x-29-advance/blob/main/lib/sync/syncService.ts): `lib/sync/syncService.ts`
- [Firebase services](https://github.com/shadhin78/x-29-advance/blob/main/lib/firebase/client.ts): `lib/firebase/client.ts`
- [Firestore](https://github.com/shadhin78/x-29-advance/blob/main/lib/firebase/firestore.ts): `lib/firebase/firestore.ts`

### Other components

- **Administrator**

## Connections

- Administrator → Login: signs in
- Login → Auth service: authenticates
- Auth service → Firebase services: uses auth (evidence: `services/authService.ts`)
- Auth gate → Auth service: checks session
- Auth gate → Dashboard shell: opens workspace
- Dashboard shell → Dashboard overview: presents overview
- Dashboard overview → Daily actions: surfaces checklist
- Dashboard overview → Exam routine: shows countdown
- Dashboard overview → Pace studio: shows progress
- Master config → Taxonomy service: edits taxonomy
- Subjects and syllabus → Study tasks: tracks chapters
- Target allocation → Daily actions: allocates targets
- Daily actions → Study tasks: updates tasks
- Schedule matrix → Subjects and syllabus: allocates study time
- Focus timer → Timer state: computes timer state
- Study tasks → IndexedDB: reads and writes (evidence: `stores/useTaskStore.ts`)
- Study tasks → Cloud sync queue: queues changes (evidence: `stores/useTaskStore.ts`)
- Cloud sync queue → IndexedDB: stores queue (evidence: `lib/sync/syncService.ts`)
- Cloud sync queue → Firebase services: checks current user (evidence: `lib/sync/syncService.ts`)
- Cloud sync queue → Firestore: writes patches (evidence: `lib/sync/syncService.ts`)
- Pace studio → Subjects and syllabus: estimates velocity
- Outcome and CGPA → Subjects and syllabus: calculates results
- Visual analytics → Study tasks: analyzes activity
