# jaynik-s/focusarc architecture

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

- Interactive diagram: https://gitdiagram.com/jaynik-s/focusarc
- Repository: https://github.com/jaynik-s/focusarc

## Overview

FocusArc is a course-based study-time tracker. Users manage course timers, start and stop sessions, then review schedule/history views and daily or weekly analytics. The React app gates private pages through authentication and a shared API client; FastAPI routes delegate persistence and reporting to service modules backed by SQLAlchemy models and PostgreSQL. The README documents the major reporting and day-summary capabilities; where their exact internal wiring was not sampled, the graph shows documented boundaries without assuming implementation details.

Main entry points: [`backend/app/api/router.py`](https://github.com/jaynik-s/focusarc/blob/main/backend/app/api/router.py) (API router), [`frontend/src/App.tsx`](https://github.com/jaynik-s/focusarc/blob/main/frontend/src/App.tsx) (App routing), [`frontend/src/api/apiClient.ts`](https://github.com/jaynik-s/focusarc/blob/main/frontend/src/api/apiClient.ts) (API client), [`backend/app/services/stats.py`](https://github.com/jaynik-s/focusarc/blob/main/backend/app/services/stats.py) (Stats services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_app["App routing<br/>[App.tsx]"]
  node_auth["Auth state<br/>[AuthContext.tsx]"]
  node_api_client["API client<br/>[apiClient.ts]"]
  node_timer_runtime["Timer runtime"]
  node_timer_page["Course timers<br/>[TimersPage.tsx]"]
  node_schedule_page["Schedule view<br/>[SchedulePage.tsx]"]
  node_history_page["Session history<br/>[HistoryPage.tsx]"]
  node_stats_page["Analytics view<br/>[StatsPage.tsx]"]
  node_timer_hook["Timer data hook<br/>[useTimers.ts]"]
  node_session_hook["Session data hook<br/>[useSessions.ts]"]
  node_stats_hooks["Reporting hooks<br/>[useAverages.ts]"]
end

subgraph group_backend["API and services"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_api_router["API router<br/>[router.py]"]
  node_auth_backend["Access checks<br/>[auth.py]"]
  node_timer_routes["Timer endpoints<br/>[timers.py]"]
  node_session_routes["Session endpoints<br/>[sessions.py]"]
  node_end_day["End day<br/>[end_day.py]"]
  node_stats_routes["Stats endpoints<br/>[stats.py]"]
  node_totals_routes["Totals endpoints<br/>[totals.py]"]
  node_timer_service["Timer services<br/>[timers.py]"]
  node_session_service["Session services<br/>[sessions.py]"]
  node_stats_service["Stats services<br/>[stats.py]"]
  node_db_session["DB session<br/>[db.py]"]
end

subgraph group_persistence["Study data"]
  node_timer_model["Course timers<br/>[timer.py]"]
  node_session_model["Study sessions<br/>[session.py]"]
  node_summary_model["Day summaries<br/>[day_summary.py]"]
  node_database[("PostgreSQL")]
end

node_user(("Student"))

node_user -->|"uses"| node_app
node_app -->|"gates pages"| node_auth
node_app -->|"routes to"| node_timer_page
node_app -->|"routes to"| node_schedule_page
node_app -->|"routes to"| node_history_page
node_app -->|"routes to"| node_stats_page
node_auth -->|"validates through"| node_api_client
node_timer_runtime -->|"requests"| node_api_client
node_session_hook -->|"requests"| node_api_client
node_stats_hooks -->|"requests"| node_api_client
node_timer_hook -->|"requests"| node_api_client
node_api_client -->|"HTTP requests"| node_api_app
node_api_app -->|"mounts"| node_api_router
node_api_router -->|"checks identity"| node_auth_backend
node_api_router -->|"dispatches"| node_timer_routes
node_api_router -->|"dispatches"| node_session_routes
node_api_router -->|"dispatches"| node_end_day
node_api_router -->|"dispatches"| node_stats_routes
node_api_router -->|"dispatches"| node_totals_routes
node_timer_routes -->|"delegates"| node_timer_service
node_session_routes -->|"delegates"| node_session_service
node_end_day -->|"delegates"| node_session_service
node_stats_routes -->|"delegates"| node_stats_service
node_totals_routes -->|"delegates"| node_stats_service
node_timer_service -->|"queries and writes"| node_db_session
node_session_service -->|"queries and writes"| node_db_session
node_stats_service -->|"aggregates data"| node_db_session
node_db_session -->|"reads and writes"| node_database
node_timer_service -->|"uses"| node_timer_model
node_session_service -->|"uses"| node_session_model
node_stats_service -->|"aggregates"| node_session_model
node_stats_service -->|"upserts summaries"| node_summary_model
node_session_model -->|"references"| node_timer_model

click node_app "https://github.com/jaynik-s/focusarc/blob/main/frontend/src/App.tsx"
click node_auth "https://github.com/jaynik-s/focusarc/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_api_client "https://github.com/jaynik-s/focusarc/blob/main/frontend/src/api/apiClient.ts"
click node_timer_runtime "https://github.com/jaynik-s/focusarc/blob/main/frontend/src/context/TimerRuntimeContext.tsx"
click node_timer_page "https://github.com/jaynik-s/focusarc/blob/main/frontend/src/routes/TimersPage.tsx"
click node_schedule_page "https://github.com/jaynik-s/focusarc/blob/main/frontend/src/routes/SchedulePage.tsx"
click node_history_page "https://github.com/jaynik-s/focusarc/blob/main/frontend/src/routes/HistoryPage.tsx"
click node_stats_page "https://github.com/jaynik-s/focusarc/blob/main/frontend/src/routes/StatsPage.tsx"
click node_timer_hook "https://github.com/jaynik-s/focusarc/blob/main/frontend/src/hooks/useTimers.ts"
click node_session_hook "https://github.com/jaynik-s/focusarc/blob/main/frontend/src/hooks/useSessions.ts"
click node_stats_hooks "https://github.com/jaynik-s/focusarc/blob/main/frontend/src/hooks/useAverages.ts"
click node_api_app "https://github.com/jaynik-s/focusarc/blob/main/backend/app/main.py"
click node_api_router "https://github.com/jaynik-s/focusarc/blob/main/backend/app/api/router.py"
click node_auth_backend "https://github.com/jaynik-s/focusarc/blob/main/backend/app/auth.py"
click node_timer_routes "https://github.com/jaynik-s/focusarc/blob/main/backend/app/api/timers.py"
click node_session_routes "https://github.com/jaynik-s/focusarc/blob/main/backend/app/api/sessions.py"
click node_end_day "https://github.com/jaynik-s/focusarc/blob/main/backend/app/api/end_day.py"
click node_stats_routes "https://github.com/jaynik-s/focusarc/blob/main/backend/app/api/stats.py"
click node_totals_routes "https://github.com/jaynik-s/focusarc/blob/main/backend/app/api/totals.py"
click node_timer_service "https://github.com/jaynik-s/focusarc/blob/main/backend/app/services/timers.py"
click node_session_service "https://github.com/jaynik-s/focusarc/blob/main/backend/app/services/sessions.py"
click node_stats_service "https://github.com/jaynik-s/focusarc/blob/main/backend/app/services/stats.py"
click node_db_session "https://github.com/jaynik-s/focusarc/blob/main/backend/app/db.py"
click node_timer_model "https://github.com/jaynik-s/focusarc/blob/main/backend/app/models/timer.py"
click node_session_model "https://github.com/jaynik-s/focusarc/blob/main/backend/app/models/session.py"
click node_summary_model "https://github.com/jaynik-s/focusarc/blob/main/backend/app/models/day_summary.py"

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_auth,node_api_client,node_timer_runtime,node_timer_page,node_schedule_page,node_history_page,node_stats_page,node_timer_hook,node_session_hook,node_stats_hooks toneBlue
class node_api_app,node_api_router,node_auth_backend,node_timer_routes,node_session_routes,node_end_day,node_stats_routes,node_totals_routes,node_timer_service,node_session_service,node_stats_service,node_db_session toneAmber
class node_timer_model,node_session_model,node_summary_model,node_database toneMint
class node_user toneIndigo
```

## Components

### Web application

- [App routing](https://github.com/jaynik-s/focusarc/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Auth state](https://github.com/jaynik-s/focusarc/blob/main/frontend/src/contexts/AuthContext.tsx): `frontend/src/contexts/AuthContext.tsx`
- [API client](https://github.com/jaynik-s/focusarc/blob/main/frontend/src/api/apiClient.ts): `frontend/src/api/apiClient.ts`
- [Timer runtime](https://github.com/jaynik-s/focusarc/blob/main/frontend/src/context/TimerRuntimeContext.tsx): `frontend/src/context/TimerRuntimeContext.tsx`
- [Course timers](https://github.com/jaynik-s/focusarc/blob/main/frontend/src/routes/TimersPage.tsx): `frontend/src/routes/TimersPage.tsx`
- [Schedule view](https://github.com/jaynik-s/focusarc/blob/main/frontend/src/routes/SchedulePage.tsx): `frontend/src/routes/SchedulePage.tsx`
- [Session history](https://github.com/jaynik-s/focusarc/blob/main/frontend/src/routes/HistoryPage.tsx): `frontend/src/routes/HistoryPage.tsx`
- [Analytics view](https://github.com/jaynik-s/focusarc/blob/main/frontend/src/routes/StatsPage.tsx): `frontend/src/routes/StatsPage.tsx`
- [Timer data hook](https://github.com/jaynik-s/focusarc/blob/main/frontend/src/hooks/useTimers.ts): `frontend/src/hooks/useTimers.ts`
- [Session data hook](https://github.com/jaynik-s/focusarc/blob/main/frontend/src/hooks/useSessions.ts): `frontend/src/hooks/useSessions.ts`
- [Reporting hooks](https://github.com/jaynik-s/focusarc/blob/main/frontend/src/hooks/useAverages.ts): `frontend/src/hooks/useAverages.ts`

### API and services

- [FastAPI app](https://github.com/jaynik-s/focusarc/blob/main/backend/app/main.py): `backend/app/main.py`
- [API router](https://github.com/jaynik-s/focusarc/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Access checks](https://github.com/jaynik-s/focusarc/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [Timer endpoints](https://github.com/jaynik-s/focusarc/blob/main/backend/app/api/timers.py): `backend/app/api/timers.py`
- [Session endpoints](https://github.com/jaynik-s/focusarc/blob/main/backend/app/api/sessions.py): `backend/app/api/sessions.py`
- [End day](https://github.com/jaynik-s/focusarc/blob/main/backend/app/api/end_day.py): `backend/app/api/end_day.py`
- [Stats endpoints](https://github.com/jaynik-s/focusarc/blob/main/backend/app/api/stats.py): `backend/app/api/stats.py`
- [Totals endpoints](https://github.com/jaynik-s/focusarc/blob/main/backend/app/api/totals.py): `backend/app/api/totals.py`
- [Timer services](https://github.com/jaynik-s/focusarc/blob/main/backend/app/services/timers.py): `backend/app/services/timers.py`
- [Session services](https://github.com/jaynik-s/focusarc/blob/main/backend/app/services/sessions.py): `backend/app/services/sessions.py`
- [Stats services](https://github.com/jaynik-s/focusarc/blob/main/backend/app/services/stats.py): `backend/app/services/stats.py`
- [DB session](https://github.com/jaynik-s/focusarc/blob/main/backend/app/db.py): `backend/app/db.py`

### Study data

- [Course timers](https://github.com/jaynik-s/focusarc/blob/main/backend/app/models/timer.py): `backend/app/models/timer.py`
- [Study sessions](https://github.com/jaynik-s/focusarc/blob/main/backend/app/models/session.py): `backend/app/models/session.py`
- [Day summaries](https://github.com/jaynik-s/focusarc/blob/main/backend/app/models/day_summary.py): `backend/app/models/day_summary.py`
- **PostgreSQL**

### Other components

- **Student**

## Connections

- Student → App routing: uses
- App routing → Auth state: gates pages
- App routing → Course timers: routes to
- App routing → Schedule view: routes to
- App routing → Session history: routes to
- App routing → Analytics view: routes to
- Auth state → API client: validates through
- Timer runtime → API client: requests
- Session data hook → API client: requests
- Reporting hooks → API client: requests
- Timer data hook → API client: requests
- API client → FastAPI app: HTTP requests
- FastAPI app → API router: mounts
- API router → Access checks: checks identity
- API router → Timer endpoints: dispatches
- API router → Session endpoints: dispatches
- API router → End day: dispatches
- API router → Stats endpoints: dispatches
- API router → Totals endpoints: dispatches
- Timer endpoints → Timer services: delegates
- Session endpoints → Session services: delegates
- End day → Session services: delegates
- Stats endpoints → Stats services: delegates
- Totals endpoints → Stats services: delegates
- Timer services → DB session: queries and writes
- Session services → DB session: queries and writes
- Stats services → DB session: aggregates data
- DB session → PostgreSQL: reads and writes
- Timer services → Course timers: uses
- Session services → Study sessions: uses
- Stats services → Study sessions: aggregates
- Stats services → Day summaries: upserts summaries
- Study sessions → Course timers: references