# prjwl458/cignotee architecture

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

- Interactive diagram: https://gitdiagram.com/prjwl458/cignotee
- Repository: https://github.com/prjwl458/cignotee

## Overview

This is a **single-device, offline-first React Native (Expo) app** for managing a **product list** (name/price/quantity) with **derived totals**, and quick **export/share** (copy/WhatsApp). There is **no backend**, **no accounts**, and **no cloud**; the “system” is primarily the **mobile client plus local persistence**.

- UI screens (route-based)
- Presentational components
- Centralized business logic (hooks/utils)
- Local storage (AsyncStorage)
- Cross-cutting concerns (theme, error boundaries/recovery)

##### App entry / navigation shell
- `App.tsx`
- `index.js`
- `app/_layout.tsx` (Expo Router layout)
- `app/index.tsx`, `app/about.tsx` (screens/routes)

These form the **Composition Root** (where providers, router, and global boundaries typically live).

##### UI (dumb/presentational)
- `src/components/*`
- `ProductForm.tsx`, `ProductItem.tsx`, `ProductList` (implicit via composition), `TotalDisplay.tsx`
- `ActionButtons.tsx`, `FooterActions.tsx` (export/share triggers likely here)
- `SplashLoader.tsx`
- `ErrorBoundary.tsx`, `GracefulRecovery.tsx`

In the README’s “Dumb UI, Smart Logic” philosophy, these should appear as **leaf nodes** that receive props and emit events.

##### State + business logic (smart layer)
- `src/hooks/useProducts.ts` (core domain workflow: CRUD, persistence, derived totals integration)
- `src/utils/calculator.ts` (pure functions; totals/price math)
- `src/constants/types.ts`, `validation.ts` (domain types & constraints)
- `src/hooks/useTheme.ts` + `src/context/ThemeContext.tsx` (theme logic)

This layer is what you want to emphasize as the “brain”: centralized logic, minimal duplicated state.

##### Platform persistence (offline)
- (Not explicitly shown as a wrapper file, but README states) **AsyncStorage**
- In practice, it will be imported/used from `useProducts.ts` (or a helper inside it).

##### Build/deploy/config (supporting, not runtime architecture)
- `app.json`, `eas.json`, `tsconfig.json`, `.eslintrc.json`, `.prettierrc`

##### Routes / Screens (app/)
- `index.tsx` (main list screen)
- `about.tsx`
- `_layout.tsx` (navigation + providers)

##### UI Components (src/components)
- Product entry/edit: `ProductForm`, `ProductItem`
- Totals: `TotalDisplay`
- Actions: `ActionButtons`, `FooterActions`
- UX resilience: `SplashLoader`, `ErrorBoundary`, `GracefulRecovery`

##### State/Logic Layer
- `useProducts` (single source of truth for product list operations)
- `calculator.ts` (pure derived computations)
- `validation.ts` (input constraints)
- `types.ts` (domain model)

##### Cross-cutting
- `ThemeContext` + `useTheme`
- `theme.ts` + `scale.ts`

##### Infrastructure dependency
- AsyncStorage (local persistence)

- Screens → Components (composition)
- Components → Hooks (event handlers call commands; hooks provide state)
- `useProducts` → AsyncStorage (persist/load)
- `useProducts` → `calculator` (compute totals; emphasize “derived state only”)
- Theme provider (`ThemeContext`) → Components/Screens (styles/theme props)

##### Product lifecycle (offline-first core)
- On app start: `useProducts` loads from **AsyncStorage** → provides products to UI
- On add/edit/remove: UI event → `useProducts` updates in-memory state → writes to AsyncStorage
- Totals: UI displays totals from `calculator(products)` (computed, not stored)

##### Export/share
- UI action (Footer/Action button) → format list (likely inside `useProducts` or utility) → OS share/copy → WhatsApp

##### Theme
- `ThemeContext` provides current theme + toggle
- Components consume theme tokens (`theme.ts`, `scale.ts`)

##### Error handling / recovery
- `ErrorBoundary` catches render errors (wrap near root)

Explicit annotations (small text callouts attached to components):

- **“Smart logic in hooks”**: `useProducts` is the central orchestrator
- **“Derived state”**: totals computed in `calculator.ts`, not stored
- **“Offline-first”**: AsyncStorage is the source of persistence; app works without network
- **“Presentational components”**: `src/components/*` are “dumb” (props in, events out)
- **“Composition root”**: `_layout.tsx` / `App.tsx` configure providers/boundaries

##### Technologies to include as labels (don’t hide the stack)
- App container: **React Native (Expo) + TypeScript**
- Routing layer: **Expo Router** (implied by `app/` + `_layout.tsx`)
- Persistence: **AsyncStorage**
- Sharing: **OS Share Sheet / Clipboard / WhatsApp**

##### Diagramming conventions (so it’s readable and “principal-grade”)

Labels like: “read”, “write”, “compute totals”, “share intent”.

##### Granularity guidance (don’t overthink—split into many components)
For *this* repo, “as many components as possible” means:

That combination will be the most accurate representation of Cignotee’s architecture: a clean offline-first client with centralized logic and dumb UI.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% A) SYSTEM CONTEXT (C4 L1-ish)
  %% =========================================================
  subgraph "A) System Context (Offline-first, single-device; no backend)"
    direction TB

    User(("User")):::external

    AppBox["Cignotee Mobile App\n(React Native (Expo) + TypeScript)"]:::app

    AsyncStorage[("Local Device Storage\nAsyncStorage")]:::external

    OSShare["OS Share Sheet / Clipboard"]:::external
    WhatsApp["WhatsApp (Target App)"]:::external

    NoBackendNote["Note: No backend • No accounts • No cloud • Works offline"]:::note

    User -->|"UI_interactions"| AppBox
    AppBox -->|"read/write_products"| AsyncStorage
    AppBox -.->|"export/share_intent"| OSShare
    OSShare -.->|"handoff"| WhatsApp

    AppBox -.->|"no_network_dependency"| NoBackendNote
  end

  %% Spacer (keeps vertical feel)
  Spacer1[" "]:::spacer

  %% =========================================================
  %% B) INTERNAL COMPONENTS (C4 L2/3 hybrid)
  %% =========================================================
  subgraph "B) Internal Component Diagram (Routes → UI → Hooks/Logic → Storage)"
    direction TB

    %% -------------------------
    %% Composition Root / Shell
    %% -------------------------
    subgraph "Composition Root / App Shell"
      direction TB
      IndexJS["index.js\n(Expo bootstrap)"]:::shell
      AppTSX["App.tsx\n(Composition root)"]:::shell
      Layout["app/_layout.tsx\n(Expo Router layout + providers)"]:::shell

      ErrorBoundary["ErrorBoundary\n(resilience boundary)"]:::resilience
      GracefulRecovery["GracefulRecovery\n(fallback UI)"]:::resilience
      SplashLoader["SplashLoader\n(startup/loading UI)"]:::ui

      IndexJS -->|"register_app"| AppTSX
      AppTSX -->|"mount_router"| Layout

      Layout -->|"wraps"| ErrorBoundary
      ErrorBoundary -->|"fallback_renders"| GracefulRecovery
      Layout -->|"may_show"| SplashLoader
    end

    %% -------------------------
    %% Routes / Screens
    %% -------------------------
    subgraph "Routes / Screens (Expo Router: app/)"
      direction TB
      MainScreen("app/index.tsx\nMain product list"):::screen
      AboutScreen("app/about.tsx\nAbout"):::screen

      Layout -->|"routes"| MainScreen
      Layout -->|"routes"| AboutScreen
    end

    %% -------------------------
    %% Presentational UI Components
    %% -------------------------
    subgraph "Presentational UI (props-in / events-out)"
      direction TB
      ProductForm["ProductForm"]:::ui
      ProductItem["ProductItem"]:::ui
      TotalDisplay["TotalDisplay"]:::ui
      ActionButtons["ActionButtons\n(export/share triggers)"]:::ui
      FooterActions["FooterActions\n(export/share triggers)"]:::ui

      DumbUINote["Principle: Presentational components are 'dumb'\n(centralized state/logic elsewhere)"]:::note
    end

    %% -------------------------
    %% State + Business Logic (Smart Layer)
    %% -------------------------
    subgraph "State + Business Logic (Smart logic in hooks)"
      direction TB
      UseProducts{{"useProducts\n(CRUD + persistence orchestration)"}}:::hook
      UseTheme{{"useTheme\n(theme logic)"}}:::hook

      SmartLogicNote["Principle: Smart logic in hooks\nSingle source of truth"]:::note
    end

    %% -------------------------
    %% Utilities / Domain
    %% -------------------------
    subgraph "Domain + Utilities (pure / shared)"
      direction TB
      Types["types\n(domain model)"]:::domain
      Validation["validation\n(input constraints)"]:::domain
      Calculator["calculator\n(derived totals math)"]:::util

      DerivedStateNote["Principle: Derived state\nTotals computed, not stored"]:::note
    end

    %% -------------------------
    %% Cross-cutting: Theme
    %% -------------------------
    subgraph "Cross-cutting: Theme System"
      direction TB
      ThemeContext["ThemeContext\n(provider)"]:::crosscut
      ThemeTokens["theme\n(design tokens)"]:::tokens
      ScaleTokens["scale\n(layout scaling)"]:::tokens
    end

    %% -------------------------
    %% Infrastructure dependency
    %% -------------------------
    subgraph "Infrastructure (Device-only)"
      direction TB
      AS2[("AsyncStorage")]:::external
      OSShare2["OS Share Sheet / Clipboard"]:::external
    end

    %% -------------------------
    %% Screen → Component composition
    %% -------------------------
    MainScreen -->|"compose"| ProductForm
    MainScreen -->|"compose"| ProductItem
    MainScreen -->|"compose"| TotalDisplay
    MainScreen -->|"compose"| ActionButtons
    MainScreen -->|"compose"| FooterActions

    %% -------------------------
    %% UI → Hooks (events/handlers, state)
    %% -------------------------
    ProductForm -->|"add/edit_events"| UseProducts
    ProductItem -->|"update/remove_events"| UseProducts
    ActionButtons -->|"export/copy_events"| UseProducts
    FooterActions -->|"export/share_events"| UseProducts

    %% -------------------------
    %% Hooks → Utilities / Domain
    %% -------------------------
    UseProducts -->|"uses_models"| Types
    UseProducts -->|"validates_input"| Validation
    UseProducts -->|"compute_totals"| Calculator
    UseProducts -->|"read/write_products"| AS2

    Validation -.->|"validates_against"| Types
    Calculator -.->|"operates_on"| Types

    %% -------------------------
    %% Theme wiring
    %% -------------------------
    Layout -->|"provides"| ThemeContext
    ThemeContext -->|"hook_access"| UseTheme
    UseTheme -->|"uses_tokens"| ThemeTokens
    UseTheme -->|"uses_tokens"| ScaleTokens

    ThemeContext -->|"theme_values"| MainScreen
    ThemeContext -->|"theme_values"| AboutScreen
    ThemeContext -->|"theme_values"| ProductForm
    ThemeContext -->|"theme_values"| ProductItem
    ThemeContext -->|"theme_values"| TotalDisplay
    ThemeContext -->|"theme_values"| ActionButtons
    ThemeContext -->|"theme_values"| FooterActions

    %% -------------------------
    %% Export/Share integration
    %% -------------------------
    UseProducts -.->|"share_intent"| OSShare2

    %% Notes links (light, non-runtime)
    DumbUINote -.->|"applies_to"| ProductForm
    SmartLogicNote -.->|"emphasize"| UseProducts
    DerivedStateNote -.->|"explains"| Calculator
  end

  %% =========================================================
  %% Click Events (from component_mapping)
  %% =========================================================
  click AppTSX "https://github.com/prjwl458/cignotee/blob/main/App.tsx"
  click IndexJS "https://github.com/prjwl458/cignotee/blob/main/index.js"
  click Layout "https://github.com/prjwl458/cignotee/blob/main/app/_layout.tsx"
  click MainScreen "https://github.com/prjwl458/cignotee/blob/main/app/index.tsx"
  click AboutScreen "https://github.com/prjwl458/cignotee/blob/main/app/about.tsx"

  click ProductForm "https://github.com/prjwl458/cignotee/blob/main/src/components/ProductForm.tsx"
  click ProductItem "https://github.com/prjwl458/cignotee/blob/main/src/components/ProductItem.tsx"
  click TotalDisplay "https://github.com/prjwl458/cignotee/blob/main/src/components/TotalDisplay.tsx"
  click ActionButtons "https://github.com/prjwl458/cignotee/blob/main/src/components/ActionButtons.tsx"
  click FooterActions "https://github.com/prjwl458/cignotee/blob/main/src/components/FooterActions.tsx"
  click SplashLoader "https://github.com/prjwl458/cignotee/blob/main/src/components/SplashLoader.tsx"
  click ErrorBoundary "https://github.com/prjwl458/cignotee/blob/main/src/components/ErrorBoundary.tsx"
  click GracefulRecovery "https://github.com/prjwl458/cignotee/blob/main/src/components/GracefulRecovery.tsx"
  click DumbUINote "https://github.com/prjwl458/cignotee/tree/main/src/components/"

  click UseProducts "https://github.com/prjwl458/cignotee/blob/main/src/hooks/useProducts.ts"
  click UseTheme "https://github.com/prjwl458/cignotee/blob/main/src/hooks/useTheme.ts"
  click ThemeContext "https://github.com/prjwl458/cignotee/blob/main/src/context/ThemeContext.tsx"

  click Calculator "https://github.com/prjwl458/cignotee/blob/main/src/utils/calculator.ts"
  click Types "https://github.com/prjwl458/cignotee/blob/main/src/constants/types.ts"
  click Validation "https://github.com/prjwl458/cignotee/blob/main/src/constants/validation.ts"
  click ThemeTokens "https://github.com/prjwl458/cignotee/blob/main/src/constants/theme.ts"
  click ScaleTokens "https://github.com/prjwl458/cignotee/blob/main/src/constants/scale.ts"

  %% =========================================================
  %% Styles
  %% =========================================================
  classDef app fill:#1f4b99,stroke:#0e2a5a,color:#ffffff,stroke-width:2px
  classDef screen fill:#2f80ed,stroke:#1b4f9c,color:#ffffff,stroke-width:2px
  classDef shell fill:#163a73,stroke:#0e2a5a,color:#ffffff,stroke-width:2px
  classDef ui fill:#e8f1ff,stroke:#2f80ed,color:#0b2447,stroke-width:1.5px
  classDef hook fill:#ffb74d,stroke:#d97706,color:#3a2200,stroke-width:2px
  classDef util fill:#ffe08a,stroke:#b45309,color:#3a2200,stroke-width:1.5px
  classDef domain fill:#ffd6a5,stroke:#c2410c,color:#3a2200,stroke-width:1.5px
  classDef crosscut fill:#b9f6ca,stroke:#0f766e,color:#053b3a,stroke-width:2px
  classDef tokens fill:#a7f3d0,stroke:#0f766e,color:#053b3a,stroke-width:1.5px
  classDef resilience fill:#fecaca,stroke:#b91c1c,color:#450a0a,stroke-width:2px
  classDef external fill:#f3f4f6,stroke:#6b7280,color:#111827,stroke-width:1.5px,stroke-dasharray:6 4
  classDef note fill:#fff7ed,stroke:#fb923c,color:#7c2d12,stroke-width:1.2px
  classDef spacer fill:#ffffff,stroke:#ffffff,color:#ffffff
```
