# sreerajraveendran/todo architecture

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

- Interactive diagram: https://gitdiagram.com/sreerajraveendran/todo
- Repository: https://github.com/sreerajraveendran/todo

## Overview

1. **Project shape**
   - This is a **React + TypeScript + Vite** single-page frontend, likely a **Todo app** based on the feature names.
   - The repository is organized around a small feature slice under `src/features`, with supporting app bootstrap, shared storage logic, and tests.

2. **Runtime and build boundary**
   - `src/main.tsx` is the application entrypoint that mounts the React tree into `index.html`.
   - Vite handles the dev server, bundling, and production build; `vite.config.ts` and `vitest.config.ts` define the build/test toolchain.
   - The app appears to be purely client-side: no backend source is present.

3. **UI composition**
   - `src/App.tsx` is the top-level application component, with `src/App.css` and `src/index.css` providing app-wide styling.
   - The feature UI is split into three focused components:
     - `TodoInput` for adding items
     - `TodoItem` for individual todo rows
     - `TodoList` for rendering the collection
   - This suggests a classic container/presenter split, where `App` or the hook owns state and the components focus on rendering and user events.

4. **State and domain logic**
   - `src/features/hooks/useTodos.ts` is the main domain hook and likely owns the todo list state, mutations, and synchronization with persistence.
   - The hook boundary is the central place where UI events become state transitions.
   - `src/features/types.ts` defines the shared todo model and keeps components and hook aligned on the same domain contract.

5. **Persistence layer**
   - `src/lib/storage.ts` is the main non-UI dependency and likely wraps browser storage, probably `localStorage`.
   - This is the key data boundary in the app: todo state is loaded from storage on startup and written back after changes.
   - The app therefore depends on a browser-provided persistence mechanism rather than a server API or database.

6. **Data flow**
   - User interaction starts in the components:
     - typing/submitting in `TodoInput`
     - toggling or deleting in `TodoItem`
   - Those actions flow into `useTodos`, which updates the in-memory todo state.
   - The hook then persists changes through `src/lib/storage.ts`, and the updated state is passed back down to `TodoList`/`TodoItem` for rerendering.

7. **Testing strategy**
   - Unit/component tests exist beside the source files:
     - `TodoInput.test.tsx`
     - `TodoItem.test.tsx`
     - `TodoList.test.tsx`
     - `useTodo.test.ts`
   - `src/setupTests.ts` and `src/test/setup.ts` indicate shared test initialization, likely for DOM matchers and test environment setup.
   - Vitest is the test runner, which fits the Vite-based frontend stack.

8. **Tooling and code quality**
   - `eslint.config.js` and TypeScript config files show static analysis and type checking are part of the workflow.
   - The repository uses multiple TS configs (`tsconfig.app.json`, `tsconfig.node.json`) to separate app and tooling contexts.
   - `vite-env.d.ts` supports Vite-specific typings.

9. **Deployment and packaging**
   - A `Dockerfile` suggests the app can be containerized for deployment.
   - `.github/workflows/deploy.yml` and `.github/actions/setup-env/action.yml` indicate CI/CD automation, likely building and deploying the static frontend artifact.
   - Because there is no server code, the deployment boundary is probably “build static assets and publish them somewhere.”

10. **Architecture summary**
   - The clean architectural split is:
     - **Presentation**: `App`, `TodoInput`, `TodoItem`, `TodoList`
     - **State/domain**: `useTodos`, `types`
     - **Persistence adapter**: `storage.ts`
     - **Platform/bootstrap**: `main.tsx`, Vite, browser DOM
   - For a diagram, show a one-way flow from UI events into the hook, then into storage, then back into UI state.

11. **What is notably absent**
   - There is no evidence of routing, server communication, global state library, or database integration.
   - The app appears intentionally small and self-contained, with browser storage as the only persistence mechanism.

Main entry points: [`src/main.tsx`](https://github.com/sreerajraveendran/todo/blob/main/src/main.tsx) (main), [`src/features/hooks/useTodos.ts`](https://github.com/sreerajraveendran/todo/blob/main/src/features/hooks/useTodos.ts) (useTodos), [`src/App.tsx`](https://github.com/sreerajraveendran/todo/blob/main/src/App.tsx) (App), [`vite.config.ts`](https://github.com/sreerajraveendran/todo/blob/main/vite.config.ts) (Vite config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI"]
  node_src_app_tsx["App<br/>root component<br/>[App.tsx]"]
  node_todo_input["TodoInput<br/>input component<br/>[TodoInput.tsx]"]
  node_todo_item["TodoItem<br/>row component<br/>[TodoItem.tsx]"]
  node_todo_list["TodoList<br/>list component<br/>[TodoList.tsx]"]
end

subgraph group_domain["Domain"]
  node_use_todos["useTodos<br/>state hook<br/>[useTodos.ts]"]
  node_todo_types["types<br/>todo model<br/>[types.ts]"]
end

subgraph group_platform["Platform"]
  node_src_main_tsx["main<br/>React entrypoint<br/>[main.tsx]"]
  node_src_app_css["App CSS<br/>app styles<br/>[App.css]"]
  node_src_index_css["Global CSS<br/>base styles<br/>[index.css]"]
  node_storage[("storage<br/>browser adapter<br/>[storage.ts]")]
end

subgraph group_tooling["Tooling"]
  node_vite_config["Vite config<br/>build config<br/>[vite.config.ts]"]
  node_vitest_config["Vitest config<br/>[vitest.config.ts]"]
  node_eslint_config["ESLint<br/>lint config<br/>[eslint.config.js]"]
  node_tsconfig_app["TS app<br/>tsconfig<br/>[tsconfig.app.json]"]
  node_tsconfig_node["TS node<br/>tsconfig<br/>[tsconfig.node.json]"]
  node_setup_tests["setupTests<br/>test bootstrap<br/>[setupTests.ts]"]
  node_test_setup["test setup<br/>test bootstrap<br/>[setup.ts]"]
  node_deploy_workflow["deploy<br/>CI workflow<br/>[deploy.yml]"]
  node_setup_action["setup-env<br/>CI action<br/>[action.yml]"]
  node_dockerfile["Dockerfile<br/>container spec"]
end

node_src_main_tsx -->|"renders"| node_src_app_tsx
node_src_main_tsx -->|"loads"| node_src_app_css
node_src_main_tsx -->|"loads"| node_src_index_css
node_src_app_tsx -->|"composes"| node_todo_input
node_src_app_tsx -->|"composes"| node_todo_list
node_todo_list -->|"renders"| node_todo_item
node_src_app_tsx -->|"uses"| node_use_todos
node_todo_input -->|"events"| node_use_todos
node_todo_item -->|"events"| node_use_todos
node_use_todos -->|"models"| node_todo_types
node_use_todos -->|"persists"| node_storage
node_storage -->|"serializes"| node_todo_types
node_vite_config -->|"builds"| node_src_main_tsx
node_vitest_config -->|"initializes"| node_setup_tests
node_vitest_config -->|"initializes"| node_test_setup
node_eslint_config -.->|"checks"| node_src_app_tsx
node_eslint_config -.->|"checks"| node_use_todos
node_tsconfig_app -.->|"types"| node_src_main_tsx
node_tsconfig_node -.->|"types"| node_vite_config
node_deploy_workflow -->|"builds"| node_vite_config
node_deploy_workflow -->|"reuses"| node_setup_action
node_dockerfile -->|"packages"| node_src_main_tsx

click node_src_main_tsx "https://github.com/sreerajraveendran/todo/blob/main/src/main.tsx"
click node_src_app_tsx "https://github.com/sreerajraveendran/todo/blob/main/src/App.tsx"
click node_src_app_css "https://github.com/sreerajraveendran/todo/blob/main/src/App.css"
click node_src_index_css "https://github.com/sreerajraveendran/todo/blob/main/src/index.css"
click node_todo_input "https://github.com/sreerajraveendran/todo/blob/main/src/features/components/TodoInput.tsx"
click node_todo_item "https://github.com/sreerajraveendran/todo/blob/main/src/features/components/TodoItem.tsx"
click node_todo_list "https://github.com/sreerajraveendran/todo/blob/main/src/features/components/TodoList.tsx"
click node_use_todos "https://github.com/sreerajraveendran/todo/blob/main/src/features/hooks/useTodos.ts"
click node_todo_types "https://github.com/sreerajraveendran/todo/blob/main/src/features/types.ts"
click node_storage "https://github.com/sreerajraveendran/todo/blob/main/src/lib/storage.ts"
click node_vite_config "https://github.com/sreerajraveendran/todo/blob/main/vite.config.ts"
click node_vitest_config "https://github.com/sreerajraveendran/todo/blob/main/vitest.config.ts"
click node_eslint_config "https://github.com/sreerajraveendran/todo/blob/main/eslint.config.js"
click node_tsconfig_app "https://github.com/sreerajraveendran/todo/blob/main/tsconfig.app.json"
click node_tsconfig_node "https://github.com/sreerajraveendran/todo/blob/main/tsconfig.node.json"
click node_setup_tests "https://github.com/sreerajraveendran/todo/blob/main/src/setupTests.ts"
click node_test_setup "https://github.com/sreerajraveendran/todo/blob/main/src/test/setup.ts"
click node_deploy_workflow "https://github.com/sreerajraveendran/todo/blob/main/.github/workflows/deploy.yml"
click node_setup_action "https://github.com/sreerajraveendran/todo/blob/main/.github/actions/setup-env/action.yml"
click node_dockerfile "https://github.com/sreerajraveendran/todo/tree/main/Dockerfile"

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_src_app_tsx,node_todo_input,node_todo_item,node_todo_list toneBlue
class node_use_todos,node_todo_types toneAmber
class node_src_main_tsx,node_src_app_css,node_src_index_css,node_storage toneMint
class node_vite_config,node_vitest_config,node_eslint_config,node_tsconfig_app,node_tsconfig_node,node_setup_tests,node_test_setup,node_deploy_workflow,node_setup_action,node_dockerfile toneRose
```

## Components

### UI

React presentation layer and feature components

- [App](https://github.com/sreerajraveendran/todo/blob/main/src/App.tsx): root component · Top-level app composition and feature wiring · `src/App.tsx`
- [TodoInput](https://github.com/sreerajraveendran/todo/blob/main/src/features/components/TodoInput.tsx): input component · Collects new todo text and submit events · `src/features/components/TodoInput.tsx`
- [TodoItem](https://github.com/sreerajraveendran/todo/blob/main/src/features/components/TodoItem.tsx): row component · Renders one todo and item actions · `src/features/components/TodoItem.tsx`
- [TodoList](https://github.com/sreerajraveendran/todo/blob/main/src/features/components/TodoList.tsx): list component · Displays the todo collection · `src/features/components/TodoList.tsx`

### Domain

Todo state and shared model

- [useTodos](https://github.com/sreerajraveendran/todo/blob/main/src/features/hooks/useTodos.ts): state hook · Owns todo state, mutations, and persistence flow · `src/features/hooks/useTodos.ts`
- [types](https://github.com/sreerajraveendran/todo/blob/main/src/features/types.ts): todo model · Shared todo domain contract · `src/features/types.ts`

### Platform

App bootstrap, browser storage, and styling

- [main](https://github.com/sreerajraveendran/todo/blob/main/src/main.tsx): React entrypoint · Mounts the app into the browser DOM · `src/main.tsx`
- [App CSS](https://github.com/sreerajraveendran/todo/blob/main/src/App.css): app styles · Application-scoped styling · `src/App.css`
- [Global CSS](https://github.com/sreerajraveendran/todo/blob/main/src/index.css): base styles · Global page and reset styles · `src/index.css`
- [storage](https://github.com/sreerajraveendran/todo/blob/main/src/lib/storage.ts): browser adapter · Wraps browser persistence for todos · `src/lib/storage.ts`

### Tooling

Build, test, lint, and delivery automation

- [Vite config](https://github.com/sreerajraveendran/todo/blob/main/vite.config.ts): build config · Dev server and production build settings · `vite.config.ts`
- [Vitest config](https://github.com/sreerajraveendran/todo/blob/main/vitest.config.ts): test config · Test runner configuration · `vitest.config.ts`
- [ESLint](https://github.com/sreerajraveendran/todo/blob/main/eslint.config.js): lint config · Static analysis rules · `eslint.config.js`
- [TS app](https://github.com/sreerajraveendran/todo/blob/main/tsconfig.app.json): tsconfig · TypeScript settings for the browser app · `tsconfig.app.json`
- [TS node](https://github.com/sreerajraveendran/todo/blob/main/tsconfig.node.json): tsconfig · TypeScript settings for tooling and Node context · `tsconfig.node.json`
- [setupTests](https://github.com/sreerajraveendran/todo/blob/main/src/setupTests.ts): test bootstrap · Shared test environment setup · `src/setupTests.ts`
- [test setup](https://github.com/sreerajraveendran/todo/blob/main/src/test/setup.ts): test bootstrap · Vitest-specific initialization · `src/test/setup.ts`
- [deploy](https://github.com/sreerajraveendran/todo/blob/main/.github/workflows/deploy.yml): CI workflow · Build and deploy automation · `.github/workflows/deploy.yml`
- [setup-env](https://github.com/sreerajraveendran/todo/blob/main/.github/actions/setup-env/action.yml): CI action · Reusable CI environment setup · `.github/actions/setup-env/action.yml`
- [Dockerfile](https://github.com/sreerajraveendran/todo/tree/main/Dockerfile): container spec · Container build for packaging or deployment · `Dockerfile`

## Connections

- main → App: renders · Bootstraps the root React tree
- main → App CSS: loads · Includes app-scoped styles
- main → Global CSS: loads · Includes global styles
- App → TodoInput: composes · Uses the input component
- App → TodoList: composes · Uses the list component
- TodoList → TodoItem: renders · Maps todos to item rows
- App → useTodos: uses · Connects UI to todo state
- TodoInput → useTodos: events · Submits new todo data
- TodoItem → useTodos: events · Sends toggle and delete actions
- useTodos → types: models · Uses the shared todo contract
- useTodos → storage: persists · Loads and saves todo data
- storage → types: serializes · Reads and writes typed todo records
- Vite config → main: builds · Targets the browser entrypoint
- Vitest config → setupTests: initializes · Shares test environment setup
- Vitest config → test setup: initializes · Loads Vitest-specific setup
- ESLint → App: checks · Applies linting across source files
- ESLint → useTodos: checks · Applies linting across source files
- TS app → main: types · Type-checks app source
- TS node → Vite config: types · Type-checks tooling config
- deploy → Vite config: builds · Uses the Vite build pipeline
- deploy → setup-env: reuses · Shares CI environment setup
- Dockerfile → main: packages · Builds the client app into an image
