How priyansh019/clockwork works
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: App.tsx App shell · server.ts API server · main.tsx Browser app · package.json Package manifest
Components 19
Frontend app
Vite/React client that owns the productivity workspace and user interaction.
- Browser app · Client-side ClockWork experience running in the browser.
src/main.tsx - App shell · Top-level application composition and navigation/state wiring.
src/App.tsx - Global styles · Shared visual system and presentation layer for the app.
src/index.css - Active workspace · Primary work surface for tasks, notes, timers, and progress.
- Planning flow · Prioritization and auto-scheduling pipeline that turns tasks into action blocks.
- Analytics views · Consistency, streak, and trend visualization over time windows.
- Focus mode · Full-screen deep focus experience with breathing, timer, and audio cues.
- Import path · CSV/XLSX timetable import feeding the shared workspace model.
- App state · Shared workspace, task, timer, and history state used across views.
Backend boundary
Thin Node entrypoint for AI requests and secret handling.
- API server · Server entrypoint that proxies structured app data to external AI services.
server.ts - Prompt shaping · Builds structured prompts from app state and user context.
- Gemini API · Google Gemini model endpoint used for prioritization, summaries, and coaching.
- Secrets config · Environment-based configuration, especially GEMINI_API_KEY.
.env.example
Support files
Static assets, metadata, and documentation around the app.
- Vite build · Frontend bundling and dev server configuration.
vite.config.ts - TypeScript config · Compiler and project settings for the codebase.
tsconfig.json - Package manifest · Dependencies and scripts for the app and backend entrypoint.
package.json - Static assets · Support files and generated artifacts used by the product or build.
assets - Metadata · Repository-level metadata consumed by tooling or the app.
metadata.json - Docs · README and project manifesto describing the product and workflow.
README.md
Connections 24
- 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.