# priyansh019/clockwork architecture

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

- Interactive diagram: https://gitdiagram.com/priyansh019/clockwork
- Repository: https://github.com/priyansh019/clockwork

## Overview

1. **Repository shape**
   - This is primarily a **single-page React application** built with **Vite** and **TypeScript**, with a small **Node/Express backend entrypoint** in `server.ts`.
   - The repo structure suggests a product-focused app rather than a multi-service system: most behavior lives in the frontend, with the backend acting as a thin integration layer.

2. **Frontend shell**
   - `src/main.tsx` is the browser bootstrap.
   - `src/App.tsx` is the main application container where the ClockWork experience is assembled.
   - `src/index.css` provides the global styling layer, and the README indicates the UI uses a polished, editorial presentation with motion and iconography.

3. **Runtime boundary**
   - The key architectural boundary is **browser UI vs. backend/API proxy**.
   - The frontend owns user interaction, task/workspace state, scheduling views, analytics screens, and focus mode.
   - The backend is there to safely reach external AI services and keep secrets out of the client bundle.

4. **AI subsystem**
   - The product’s differentiator is its **Gemini-backed AI pipeline**.
   - The README describes AI functions such as task prioritization, urgency ranking, day summarization, schedule-block generation, and coaching feedback.
   - `server.ts` is likely responsible for receiving structured app state from the client, shaping prompts, and forwarding requests to the **Google Gemini API** using `GEMINI_API_KEY`.

5. **Core user/workspace flow**
   - The main flow is: **onboard workspace/profile → capture tasks and notes → prioritize with AI → time-block the day → track progress and streaks**.
   - This is the central product loop and should be treated as the primary data flow when diagramming the system.

6. **Productivity workspace**
   - The “Active Workspace” described in the README appears to be the main operational area for:
     - task pipeline management
     - live clock/timer behavior
     - progress/streak tracking
     - sticky notes / quick capture
   - This is likely the highest-frequency interaction surface in the app.

7. **Planning and scheduling**
   - A distinct functional subsystem handles **prioritization and auto-scheduling**.
   - It turns a list of tasks into ordered action blocks such as **Focus**, **Admin**, and **Break** segments.
   - This scheduling logic is likely a mix of client-side state transformation and AI-generated recommendations, with the server used for AI calls.

8. **Analytics and momentum**
   - Another major UI subsystem is **productivity analytics**: streaks, consistency, and trend visualization over 7/14/30 day windows.
   - The README mentions **Recharts**, so this subsystem is visual and metrics-driven rather than storage-driven.
   - Since no database is visible in the tree, these metrics are likely derived from app state or browser-stored history.

9. **Import and onboarding**
   - The app supports **CSV/XLSX timetable import**, which is a separate ingestion path from normal task entry.
   - This is important architecturally because it introduces a file-processing boundary in the frontend, feeding imported events into the same scheduling/workspace model.

10. **Deep Focus mode**
   - The app includes a dedicated **full-screen focus experience** with breathing guidance, timer behavior, and audio cues.
   - This should be treated as a specialized execution mode of the frontend rather than a separate subsystem.
   - It likely consumes the same task/timer state but presents it with a distraction-free interaction model.

11. **External services and configuration**
   - The only explicitly named external service is **Google Gemini**.
   - `.env.example` indicates environment-based configuration, especially for the API key.
   - No database, queue, or third-party backend service is evident from the tree, so the architecture appears lightweight and client-centric.

12. **Assets and supporting materials**
   - `assets/` contains static/support files; `assets/.aistudio` suggests some AI Studio-related metadata or generated artifacts.
   - `metadata.json` likely holds app/product metadata used by the frontend or build tooling.
   - `docs.md` and `PROJECT_MANIFESTO.md` are documentation assets, not runtime components.

13. **Deployment/build boundary**
   - `vite.config.ts`, `tsconfig.json`, `package.json`, and `package-lock.json` show a standard Vite/TypeScript build pipeline.
   - The architectural deployment model is likely: **build frontend assets with Vite, run locally in the browser, and use the Node backend only for AI-related server duties**.

14. **What is not present**
   - There is no visible sign of a separate persistence layer, auth service, message queue, or multi-tenant backend.
   - For an architecture diagram, it would be accurate to show a **single frontend application**, a **minimal Express backend**, and **Gemini as the external intelligence service**, with all other features living inside the client app.

Main entry points: [`src/App.tsx`](https://github.com/priyansh019/clockwork/blob/main/src/App.tsx) (App shell), [`server.ts`](https://github.com/priyansh019/clockwork/blob/main/server.ts) (API server), [`src/main.tsx`](https://github.com/priyansh019/clockwork/blob/main/src/main.tsx) (Browser app), [`package.json`](https://github.com/priyansh019/clockwork/blob/main/package.json) (Package manifest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_frontend["Frontend app"]
  node_node_main["Browser app<br/>react SPA<br/>[main.tsx]"]
  node_node_app["App shell<br/>ui container<br/>[App.tsx]"]
  node_node_styles["Global styles<br/>css theme<br/>[index.css]"]
  node_node_workspace["Active workspace<br/>productivity hub"]
  node_node_planning["Planning flow<br/>schedule logic"]
  node_node_analytics["Analytics views<br/>metrics UI"]
  node_node_focus["Focus mode<br/>immersive timer"]
  node_node_import["Import path<br/>file ingestion"]
  node_node_state[("App state<br/>client state")]
end

subgraph group_group_backend["Backend boundary"]
  node_node_server["API server<br/>node express<br/>[server.ts]"]
  node_node_prompt["Prompt shaping<br/>ai orchestration"]
  node_node_gemini(("Gemini API<br/>external ai"))
  node_node_env["Secrets config<br/>env config<br/>[.env.example]"]
end

subgraph group_group_support["Support files"]
  node_node_build["Vite build<br/>tooling<br/>[vite.config.ts]"]
  node_node_types["TypeScript config<br/>tooling<br/>[tsconfig.json]"]
  node_node_manifest["Package manifest<br/>tooling<br/>[package.json]"]
  node_node_assets["Static assets"]
  node_node_metadata["Metadata<br/>[metadata.json]"]
  node_node_docs["Docs<br/>documentation<br/>[README.md]"]
end

node_node_main -->|"boots"| node_node_app
node_node_app -->|"uses"| node_node_styles
node_node_app -->|"hosts"| node_node_workspace
node_node_app -->|"routes to"| node_node_planning
node_node_app -->|"shows"| node_node_analytics
node_node_app -->|"enters"| node_node_focus
node_node_app -->|"ingests"| node_node_import
node_node_workspace -->|"reads/writes"| node_node_state
node_node_planning -->|"transforms"| node_node_state
node_node_analytics -->|"derives from"| node_node_state
node_node_focus -->|"consumes"| node_node_state
node_node_import -->|"feeds"| node_node_state
node_node_main -->|"calls"| node_node_server
node_node_server -->|"shapes"| node_node_prompt
node_node_prompt -->|"requests"| node_node_gemini
node_node_env -->|"configures"| node_node_server
node_node_server -->|"reads"| node_node_env
node_node_build -->|"bundles"| node_node_main
node_node_types -->|"types"| node_node_main
node_node_manifest -->|"declares"| node_node_build
node_node_manifest -->|"includes"| node_node_server
node_node_assets -->|"supports"| node_node_app
node_node_metadata -->|"describes"| node_node_app
node_node_docs -.->|"documents"| node_node_app

click node_node_main "https://github.com/priyansh019/clockwork/blob/main/src/main.tsx"
click node_node_app "https://github.com/priyansh019/clockwork/blob/main/src/App.tsx"
click node_node_styles "https://github.com/priyansh019/clockwork/blob/main/src/index.css"
click node_node_server "https://github.com/priyansh019/clockwork/blob/main/server.ts"
click node_node_env "https://github.com/priyansh019/clockwork/blob/main/.env.example"
click node_node_build "https://github.com/priyansh019/clockwork/blob/main/vite.config.ts"
click node_node_types "https://github.com/priyansh019/clockwork/blob/main/tsconfig.json"
click node_node_manifest "https://github.com/priyansh019/clockwork/blob/main/package.json"
click node_node_assets "https://github.com/priyansh019/clockwork/tree/main/assets"
click node_node_metadata "https://github.com/priyansh019/clockwork/blob/main/metadata.json"
click node_node_docs "https://github.com/priyansh019/clockwork/blob/main/README.md"

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_node_main,node_node_app,node_node_styles,node_node_workspace,node_node_planning,node_node_analytics,node_node_focus,node_node_import,node_node_state toneBlue
class node_node_server,node_node_prompt,node_node_gemini,node_node_env toneAmber
class node_node_build,node_node_types,node_node_manifest,node_node_assets,node_node_metadata,node_node_docs toneMint
```

## Components

### Frontend app

Vite/React client that owns the productivity workspace and user interaction.

- [Browser app](https://github.com/priyansh019/clockwork/blob/main/src/main.tsx): react SPA · Client-side ClockWork experience running in the browser. · `src/main.tsx`
- [App shell](https://github.com/priyansh019/clockwork/blob/main/src/App.tsx): ui container · Top-level application composition and navigation/state wiring. · `src/App.tsx`
- [Global styles](https://github.com/priyansh019/clockwork/blob/main/src/index.css): css theme · Shared visual system and presentation layer for the app. · `src/index.css`
- **Active workspace**: productivity hub · Primary work surface for tasks, notes, timers, and progress.
- **Planning flow**: schedule logic · Prioritization and auto-scheduling pipeline that turns tasks into action blocks.
- **Analytics views**: metrics UI · Consistency, streak, and trend visualization over time windows.
- **Focus mode**: immersive timer · Full-screen deep focus experience with breathing, timer, and audio cues.
- **Import path**: file ingestion · CSV/XLSX timetable import feeding the shared workspace model.
- **App state**: client state · Shared workspace, task, timer, and history state used across views.

### Backend boundary

Thin Node entrypoint for AI requests and secret handling.

- [API server](https://github.com/priyansh019/clockwork/blob/main/server.ts): node express · Server entrypoint that proxies structured app data to external AI services. · `server.ts`
- **Prompt shaping**: ai orchestration · Builds structured prompts from app state and user context.
- **Gemini API**: external ai · Google Gemini model endpoint used for prioritization, summaries, and coaching.
- [Secrets config](https://github.com/priyansh019/clockwork/blob/main/.env.example): env config · Environment-based configuration, especially GEMINI_API_KEY. · `.env.example`

### Support files

Static assets, metadata, and documentation around the app.

- [Vite build](https://github.com/priyansh019/clockwork/blob/main/vite.config.ts): tooling · Frontend bundling and dev server configuration. · `vite.config.ts`
- [TypeScript config](https://github.com/priyansh019/clockwork/blob/main/tsconfig.json): tooling · Compiler and project settings for the codebase. · `tsconfig.json`
- [Package manifest](https://github.com/priyansh019/clockwork/blob/main/package.json): tooling · Dependencies and scripts for the app and backend entrypoint. · `package.json`
- [Static assets](https://github.com/priyansh019/clockwork/tree/main/assets): assets · Support files and generated artifacts used by the product or build. · `assets`
- [Metadata](https://github.com/priyansh019/clockwork/blob/main/metadata.json): app metadata · Repository-level metadata consumed by tooling or the app. · `metadata.json`
- [Docs](https://github.com/priyansh019/clockwork/blob/main/README.md): documentation · README and project manifesto describing the product and workflow. · `README.md`

## Connections

- Browser app → App shell: boots · Browser entry mounts the main application shell.
- App shell → Global styles: uses · App shell consumes global styling and theme rules.
- App shell → Active workspace: hosts · Primary container for the active productivity workspace.
- App shell → Planning flow: routes to · App shell connects tasks into planning and scheduling flows.
- App shell → Analytics views: shows · App shell exposes productivity metrics and trends.
- App shell → Focus mode: enters · App shell can switch into the deep focus experience.
- App shell → Import path: ingests · App shell accepts timetable and task imports.
- Active workspace → App state: reads/writes · Workspace interaction updates shared client state.
- Planning flow → App state: transforms · Planning logic converts workspace state into ordered blocks.
- Analytics views → App state: derives from · Analytics are computed from task and history state.
- Focus mode → App state: consumes · Focus mode uses current task and timer state.
- Import path → App state: feeds · Imported files populate the shared workspace model.
- Browser app → API server: calls · Client sends structured state to the backend for AI requests.
- API server → Prompt shaping: shapes · Server prepares prompts and request payloads for Gemini.
- Prompt shaping → Gemini API: requests · Prompted AI operations are forwarded to the Gemini API.
- Secrets config → API server: configures · Environment variables provide secrets and service configuration.
- API server → Secrets config: reads · Backend reads API key configuration from environment.
- Vite build → Browser app: bundles · Vite builds and serves the browser application.
- TypeScript config → Browser app: types · TypeScript settings govern the client codebase.
- Package manifest → Vite build: declares · Project scripts and dependencies define the build/runtime setup.
- Package manifest → API server: includes · Package manifest includes the backend entrypoint in the runtime.
- Static assets → App shell: supports · Static assets and generated artifacts support the UI.
- Metadata → App shell: describes · Repository metadata supplements the application experience.
- Docs → App shell: documents · Docs explain the product vision and usage.
