# metalha516/procastinot architecture

> Architecture diagram of the GitHub repository metalha516/procastinot, 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/metalha516/procastinot
- Repository: https://github.com/metalha516/procastinot

## Overview

ProcastiNot is a student focus web app whose main workflow is starting a Pomodoro session, optionally pairing it with synthesized focus audio, and recording completed focus for personal progress and rewards. Its broader features include circadian task planning, exam preparation, distraction interventions, and gated study-community and telemetry views. The app wires providers in `src/App.tsx`; README-described UI connections supplement the sampled source, while unsampled backend-like features are not represented as external services. The project describes rooms and peer features, but the supplied evidence does not establish a live networking service.

Main entry points: [`src/context/GamificationContext.tsx`](https://github.com/metalha516/procastinot/blob/main/src/context/GamificationContext.tsx) (Gamification State), [`src/context/TimerContext.tsx`](https://github.com/metalha516/procastinot/blob/main/src/context/TimerContext.tsx) (Timer State), [`src/App.tsx`](https://github.com/metalha516/procastinot/blob/main/src/App.tsx) (App Providers), [`src/components/layout/Shell.tsx`](https://github.com/metalha516/procastinot/blob/main/src/components/layout/Shell.tsx) (App Shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Shell"]
  node_app["App Providers<br/>[App.tsx]"]
  node_shell["App Shell<br/>[Shell.tsx]"]
  node_auth["Auth State<br/>[AuthContext.tsx]"]
end

subgraph group_focus["Focus Session"]
  node_timer_ui["Pomodoro Timer<br/>[PomodoroTimer.tsx]"]
  node_timer_state["Timer State<br/>[TimerContext.tsx]"]
  node_gamma_controls["Gamma Controls"]
  node_audio_engine["Audio Engine<br/>[gammaEngine.ts]"]
end

subgraph group_planning["Academic Planning"]
  node_planner["Study Planner<br/>[AIStudyPlanner.tsx]"]
  node_circadian["Circadian Organizer"]
  node_exam["Exam Countdown<br/>[ExamCountdown.tsx]"]
  node_task_state["Task State<br/>[TaskContext.tsx]"]
end

subgraph group_engagement["Shield And Rewards"]
  node_blocker["Distraction Blocker"]
  node_second_thought["Second Thought"]
  node_shield_hook["Browser Shield"]
  node_extension["Browser Companion<br/>[background.js]"]
  node_game_state["Gamification State"]
end

subgraph group_student["Student Features"]
  node_auth_gate["Feature Gate"]
  node_auth_modal["Sign In<br/>[AuthModal.tsx]"]
  node_dashboard["Overview Dashboard"]
  node_heatmap["Streak Heatmap<br/>[StreakHeatmap.tsx]"]
  node_performance["Performance Curve"]
  node_leaderboard["Leaderboard"]
  node_rooms["Focus Rooms"]
  node_shop["Reward Shop<br/>[RewardShop.tsx]"]
end

node_student_actor(("Student"))
node_browser_audio["Web Audio API"]
node_broadcast["Timer Broadcast"]

node_student_actor -->|"uses"| node_shell
node_app -->|"renders"| node_shell
node_app -->|"provides"| node_auth
node_app -->|"provides"| node_task_state
node_app -->|"provides"| node_game_state
node_app -->|"provides"| node_timer_state
node_shell -->|"presents"| node_timer_ui
node_timer_ui -->|"controls"| node_timer_state
node_gamma_controls -->|"updates settings"| node_timer_state
node_timer_state -->|"controls audio"| node_audio_engine
node_audio_engine -->|"synthesizes with"| node_browser_audio
node_timer_state -->|"synchronizes tabs"| node_broadcast
node_timer_state -->|"reports completion"| node_game_state
node_shell -->|"gates features"| node_auth_gate
node_auth_gate -->|"checks access"| node_auth
node_auth_modal -->|"authenticates"| node_auth
node_planner -->|"uses tasks"| node_task_state
node_circadian -->|"uses schedule"| node_task_state
node_exam -->|"uses deadlines"| node_task_state
node_blocker -->|"intercepts links"| node_shield_hook
node_shield_hook -->|"records interception"| node_game_state
node_extension -.->|"redirects to app"| node_shield_hook
node_second_thought -->|"records intervention"| node_game_state
node_dashboard -->|"reads progress"| node_game_state
node_heatmap -->|"reads streaks"| node_game_state
node_performance -->|"reads performance"| node_game_state
node_leaderboard -->|"reads standings"| node_game_state
node_rooms -->|"uses engagement"| node_game_state
node_shop -->|"uses rewards"| node_game_state

click node_app "https://github.com/metalha516/procastinot/blob/main/src/App.tsx"
click node_shell "https://github.com/metalha516/procastinot/blob/main/src/components/layout/Shell.tsx"
click node_auth "https://github.com/metalha516/procastinot/blob/main/src/context/AuthContext.tsx"
click node_auth_gate "https://github.com/metalha516/procastinot/blob/main/src/components/auth/AuthFeatureGate.tsx"
click node_auth_modal "https://github.com/metalha516/procastinot/blob/main/src/components/auth/AuthModal.tsx"
click node_timer_ui "https://github.com/metalha516/procastinot/blob/main/src/components/timer/PomodoroTimer.tsx"
click node_timer_state "https://github.com/metalha516/procastinot/blob/main/src/context/TimerContext.tsx"
click node_gamma_controls "https://github.com/metalha516/procastinot/blob/main/src/components/timer/GammaWaveControls.tsx"
click node_audio_engine "https://github.com/metalha516/procastinot/blob/main/src/audio/gammaEngine.ts"
click node_planner "https://github.com/metalha516/procastinot/blob/main/src/components/planner/AIStudyPlanner.tsx"
click node_circadian "https://github.com/metalha516/procastinot/blob/main/src/components/planner/CircadianOrganizer.tsx"
click node_exam "https://github.com/metalha516/procastinot/blob/main/src/components/planner/ExamCountdown.tsx"
click node_task_state "https://github.com/metalha516/procastinot/blob/main/src/context/TaskContext.tsx"
click node_blocker "https://github.com/metalha516/procastinot/blob/main/src/components/distraction/DistractionBlocker.tsx"
click node_second_thought "https://github.com/metalha516/procastinot/blob/main/src/components/distraction/SecondThoughtModal.tsx"
click node_shield_hook "https://github.com/metalha516/procastinot/blob/main/src/hooks/useBrowserShield.ts"
click node_extension "https://github.com/metalha516/procastinot/blob/main/public/extension/background.js"
click node_game_state "https://github.com/metalha516/procastinot/blob/main/src/context/GamificationContext.tsx"
click node_dashboard "https://github.com/metalha516/procastinot/blob/main/src/components/dashboard/OverviewDashboard.tsx"
click node_heatmap "https://github.com/metalha516/procastinot/blob/main/src/components/gamification/StreakHeatmap.tsx"
click node_performance "https://github.com/metalha516/procastinot/blob/main/src/components/gamification/PerformanceDeltaCurve.tsx"
click node_leaderboard "https://github.com/metalha516/procastinot/blob/main/src/components/gamification/LeaderboardArena.tsx"
click node_rooms "https://github.com/metalha516/procastinot/blob/main/src/components/rooms/VirtualFocusRooms.tsx"
click node_shop "https://github.com/metalha516/procastinot/blob/main/src/components/gamification/RewardShop.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_shell,node_auth toneBlue
class node_timer_ui,node_timer_state,node_gamma_controls,node_audio_engine toneAmber
class node_planner,node_circadian,node_exam,node_task_state,node_browser_audio toneMint
class node_blocker,node_second_thought,node_shield_hook,node_extension,node_game_state toneRose
class node_auth_gate,node_auth_modal,node_dashboard,node_heatmap,node_performance,node_leaderboard,node_rooms,node_shop,node_student_actor,node_broadcast toneIndigo
```

## Components

### App Shell

- [App Providers](https://github.com/metalha516/procastinot/blob/main/src/App.tsx): `src/App.tsx`
- [App Shell](https://github.com/metalha516/procastinot/blob/main/src/components/layout/Shell.tsx): `src/components/layout/Shell.tsx`
- [Auth State](https://github.com/metalha516/procastinot/blob/main/src/context/AuthContext.tsx): `src/context/AuthContext.tsx`

### Focus Session

- [Pomodoro Timer](https://github.com/metalha516/procastinot/blob/main/src/components/timer/PomodoroTimer.tsx): `src/components/timer/PomodoroTimer.tsx`
- [Timer State](https://github.com/metalha516/procastinot/blob/main/src/context/TimerContext.tsx): `src/context/TimerContext.tsx`
- [Gamma Controls](https://github.com/metalha516/procastinot/blob/main/src/components/timer/GammaWaveControls.tsx): `src/components/timer/GammaWaveControls.tsx`
- [Audio Engine](https://github.com/metalha516/procastinot/blob/main/src/audio/gammaEngine.ts): `src/audio/gammaEngine.ts`

### Academic Planning

- [Study Planner](https://github.com/metalha516/procastinot/blob/main/src/components/planner/AIStudyPlanner.tsx): `src/components/planner/AIStudyPlanner.tsx`
- [Circadian Organizer](https://github.com/metalha516/procastinot/blob/main/src/components/planner/CircadianOrganizer.tsx): `src/components/planner/CircadianOrganizer.tsx`
- [Exam Countdown](https://github.com/metalha516/procastinot/blob/main/src/components/planner/ExamCountdown.tsx): `src/components/planner/ExamCountdown.tsx`
- [Task State](https://github.com/metalha516/procastinot/blob/main/src/context/TaskContext.tsx): `src/context/TaskContext.tsx`

### Shield And Rewards

- [Distraction Blocker](https://github.com/metalha516/procastinot/blob/main/src/components/distraction/DistractionBlocker.tsx): `src/components/distraction/DistractionBlocker.tsx`
- [Second Thought](https://github.com/metalha516/procastinot/blob/main/src/components/distraction/SecondThoughtModal.tsx): `src/components/distraction/SecondThoughtModal.tsx`
- [Browser Shield](https://github.com/metalha516/procastinot/blob/main/src/hooks/useBrowserShield.ts): `src/hooks/useBrowserShield.ts`
- [Browser Companion](https://github.com/metalha516/procastinot/blob/main/public/extension/background.js): `public/extension/background.js`
- [Gamification State](https://github.com/metalha516/procastinot/blob/main/src/context/GamificationContext.tsx): `src/context/GamificationContext.tsx`

### Student Features

- [Feature Gate](https://github.com/metalha516/procastinot/blob/main/src/components/auth/AuthFeatureGate.tsx): `src/components/auth/AuthFeatureGate.tsx`
- [Sign In](https://github.com/metalha516/procastinot/blob/main/src/components/auth/AuthModal.tsx): `src/components/auth/AuthModal.tsx`
- [Overview Dashboard](https://github.com/metalha516/procastinot/blob/main/src/components/dashboard/OverviewDashboard.tsx): `src/components/dashboard/OverviewDashboard.tsx`
- [Streak Heatmap](https://github.com/metalha516/procastinot/blob/main/src/components/gamification/StreakHeatmap.tsx): `src/components/gamification/StreakHeatmap.tsx`
- [Performance Curve](https://github.com/metalha516/procastinot/blob/main/src/components/gamification/PerformanceDeltaCurve.tsx): `src/components/gamification/PerformanceDeltaCurve.tsx`
- [Leaderboard](https://github.com/metalha516/procastinot/blob/main/src/components/gamification/LeaderboardArena.tsx): `src/components/gamification/LeaderboardArena.tsx`
- [Focus Rooms](https://github.com/metalha516/procastinot/blob/main/src/components/rooms/VirtualFocusRooms.tsx): `src/components/rooms/VirtualFocusRooms.tsx`
- [Reward Shop](https://github.com/metalha516/procastinot/blob/main/src/components/gamification/RewardShop.tsx): `src/components/gamification/RewardShop.tsx`

### Other components

- **Student**
- **Web Audio API**
- **Timer Broadcast**

## Connections

- Student → App Shell: uses
- App Providers → App Shell: renders
- App Providers → Auth State: provides
- App Providers → Task State: provides
- App Providers → Gamification State: provides
- App Providers → Timer State: provides
- App Shell → Pomodoro Timer: presents
- Pomodoro Timer → Timer State: controls
- Gamma Controls → Timer State: updates settings
- Timer State → Audio Engine: controls audio
- Audio Engine → Web Audio API: synthesizes with
- Timer State → Timer Broadcast: synchronizes tabs
- Timer State → Gamification State: reports completion
- App Shell → Feature Gate: gates features
- Feature Gate → Auth State: checks access
- Sign In → Auth State: authenticates
- Study Planner → Task State: uses tasks
- Circadian Organizer → Task State: uses schedule
- Exam Countdown → Task State: uses deadlines
- Distraction Blocker → Browser Shield: intercepts links
- Browser Shield → Gamification State: records interception
- Browser Companion → Browser Shield: redirects to app
- Second Thought → Gamification State: records intervention
- Overview Dashboard → Gamification State: reads progress
- Streak Heatmap → Gamification State: reads streaks
- Performance Curve → Gamification State: reads performance
- Leaderboard → Gamification State: reads standings
- Focus Rooms → Gamification State: uses engagement
- Reward Shop → Gamification State: uses rewards