# johnleshan/tracksimply architecture

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

- Interactive diagram: https://gitdiagram.com/johnleshan/tracksimply
- Repository: https://github.com/johnleshan/tracksimply

## Overview

#### Purpose and Entry Points
This is a Vite-built React single-page application for business/personal operations management: dashboard, accounts, bookkeeping, budgets, debt, inventory, vehicles, and AI assistance. The browser bootstrap is `src/main.jsx`; application composition and top-level routing/state layout are centered in `src/App.jsx`. Styling is primarily colocated CSS plus global styles in `src/index.css` and `src/App.css`.

#### Application Shell and Navigation
The persistent UI shell is built from navigation and workspace components:
- `src/components/Navbar.jsx`
- `src/components/Sidebar.jsx`
- `src/App.jsx`

The sidebar likely selects operational tools while the app root controls which tool/workspace is rendered. Product-oriented UI is separated into reusable display/detail components at `src/components/ProductCard.jsx` and `src/components/ProductModal.jsx`.

#### Authentication and Data Boundary
Authentication state is centralized through React context in `src/context/AuthContext.jsx`. Supabase client creation/configuration is isolated at `src/lib/supabase.js`, forming the principal boundary between browser UI and backend authentication/database services.

Tool components should consume authenticated state rather than own credential handling. The repository includes database validation, RLS, user, and deployment investigation scripts under `scratch/`, indicating Supabase database policies and user access are material operational concerns.

#### Operational Tool Modules
The primary domain stages are independent React tool views under `src/components/tools/`:
- Dashboard aggregation: `DashboardOverview.jsx`
- Account/user administration: `AccountManager.jsx`
- Financial records: `Bookkeeping.jsx`
- Planning and liabilities: `BudgetPlanner.jsx`, `DebtTracker.jsx`
- Operational assets: `InventoryTracker.jsx`, `VehicleManagement.jsx`

These modules are the core feature boundary: each owns domain-specific UI and likely reads/writes its related Supabase tables, while shared authentication and navigation remain outside them.

#### AI Assistance Flow
`src/components/MagicAI.jsx` provides the user-facing AI interaction surface. Requests are delegated through `src/services/aiService.js`, keeping model/API invocation separate from presentation code. The presence of `scratch/test_groq.cjs` suggests Groq is the intended or tested external AI provider; secrets should be supplied through environment configuration rather than frontend source.

#### Data, Deployment, and Infrastructure
CSV files in `data/` provide seed/import-oriented business datasets for budgets, debts, inventory, users, and transactions, e.g. `data/budgets.csv` and `data/transactions.csv`. Database initialization is represented by `scratch/initialize_database.sql`.

The frontend is configured as a Vite application via `vite.config.js`, with Vercel deployment configuration in `vercel.json`. `.env.example` defines the expected environment-variable contract for services such as Supabase and AI integration.

Main entry points: [`src/App.jsx`](https://github.com/johnleshan/tracksimply/blob/master/src/App.jsx) (App shell and routing), [`src/lib/supabase.js`](https://github.com/johnleshan/tracksimply/blob/master/src/lib/supabase.js) (Supabase client), [`src/components/Sidebar.jsx`](https://github.com/johnleshan/tracksimply/blob/master/src/components/Sidebar.jsx) (Tool navigation), [`src/services/aiService.js`](https://github.com/johnleshan/tracksimply/blob/master/src/services/aiService.js) (AI request service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React application"]
  node_bootstrap["Browser bootstrap<br/>React entry<br/>[main.jsx]"]
  node_app["App shell and routing<br/>React root<br/>[App.jsx]"]
  node_navbar["Top navigation<br/>UI component<br/>[Navbar.jsx]"]
  node_sidebar["Tool navigation<br/>UI component<br/>[Sidebar.jsx]"]
  node_product_ui["Product detail UI<br/>UI components<br/>[ProductCard.jsx]"]
  node_dashboard["Dashboard overview<br/>tool view"]
  node_account_manager["Account management<br/>tool view<br/>[AccountManager.jsx]"]
  node_finance_tools["Finance planning tools<br/>tool views<br/>[Bookkeeping.jsx]"]
  node_asset_tools["Asset operations tools<br/>tool views"]
  node_magic_ai["Magic AI UI<br/>AI component<br/>[MagicAI.jsx]"]
end

subgraph group_services["Service boundary"]
  node_auth_context["Authentication state<br/>React context<br/>[AuthContext.jsx]"]
  node_supabase[("Supabase client<br/>backend client<br/>[supabase.js]")]
  node_ai_service["AI request service<br/>service module<br/>[aiService.js]"]
  node_groq{{"Groq provider<br/>external AI provider<br/>[test_groq.cjs]"}}
end

subgraph group_data["Data and operations"]
  node_seed_data["Business CSV data<br/>seed/import data<br/>[budgets.csv]"]
  node_database_init["Database initialization<br/>SQL setup"]
end

subgraph group_delivery["Build and deployment"]
  node_environment["Environment contract<br/>environment template<br/>[.env.example]"]
  node_vite["Vite build<br/>build configuration<br/>[vite.config.js]"]
  node_vercel["Vercel deployment<br/>deployment configuration<br/>[vercel.json]"]
end

node_bootstrap -->|"mounts"| node_app
node_app -->|"renders"| node_navbar
node_app -->|"renders"| node_sidebar
node_sidebar -->|"selects"| node_dashboard
node_sidebar -->|"selects"| node_account_manager
node_sidebar -->|"selects"| node_finance_tools
node_sidebar -->|"selects"| node_asset_tools
node_app -->|"uses"| node_product_ui
node_app -->|"renders"| node_magic_ai
node_app -->|"provides state"| node_auth_context
node_auth_context -->|"authenticates through"| node_supabase
node_dashboard -->|"reads operational data"| node_supabase
node_account_manager -->|"manages users"| node_supabase
node_finance_tools -->|"reads and writes records"| node_supabase
node_asset_tools -->|"reads and writes assets"| node_supabase
node_magic_ai -->|"delegates requests"| node_ai_service
node_ai_service -->|"invokes model"| node_groq
node_environment -.->|"supplies configuration"| node_supabase
node_environment -.->|"supplies secrets"| node_ai_service
node_seed_data -.->|"supports import"| node_database_init
node_database_init -.->|"initializes"| node_supabase
node_vite -->|"builds"| node_bootstrap
node_vercel -->|"deploys build"| node_vite

click node_bootstrap "https://github.com/johnleshan/tracksimply/blob/master/src/main.jsx"
click node_app "https://github.com/johnleshan/tracksimply/blob/master/src/App.jsx"
click node_navbar "https://github.com/johnleshan/tracksimply/blob/master/src/components/Navbar.jsx"
click node_sidebar "https://github.com/johnleshan/tracksimply/blob/master/src/components/Sidebar.jsx"
click node_product_ui "https://github.com/johnleshan/tracksimply/blob/master/src/components/ProductCard.jsx"
click node_dashboard "https://github.com/johnleshan/tracksimply/blob/master/src/components/tools/DashboardOverview.jsx"
click node_account_manager "https://github.com/johnleshan/tracksimply/blob/master/src/components/tools/AccountManager.jsx"
click node_finance_tools "https://github.com/johnleshan/tracksimply/blob/master/src/components/tools/Bookkeeping.jsx"
click node_asset_tools "https://github.com/johnleshan/tracksimply/blob/master/src/components/tools/InventoryTracker.jsx"
click node_magic_ai "https://github.com/johnleshan/tracksimply/blob/master/src/components/MagicAI.jsx"
click node_auth_context "https://github.com/johnleshan/tracksimply/blob/master/src/context/AuthContext.jsx"
click node_supabase "https://github.com/johnleshan/tracksimply/blob/master/src/lib/supabase.js"
click node_ai_service "https://github.com/johnleshan/tracksimply/blob/master/src/services/aiService.js"
click node_groq "https://github.com/johnleshan/tracksimply/blob/master/scratch/test_groq.cjs"
click node_seed_data "https://github.com/johnleshan/tracksimply/blob/master/data/budgets.csv"
click node_database_init "https://github.com/johnleshan/tracksimply/blob/master/scratch/initialize_database.sql"
click node_environment "https://github.com/johnleshan/tracksimply/blob/master/.env.example"
click node_vite "https://github.com/johnleshan/tracksimply/blob/master/vite.config.js"
click node_vercel "https://github.com/johnleshan/tracksimply/blob/master/vercel.json"

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_bootstrap,node_app,node_navbar,node_sidebar,node_product_ui,node_dashboard,node_account_manager,node_finance_tools,node_asset_tools,node_magic_ai toneBlue
class node_auth_context,node_supabase,node_ai_service,node_groq toneAmber
class node_seed_data,node_database_init toneMint
class node_environment,node_vite,node_vercel toneRose
```

## Components

### React application

Browser SPA shell and operational workspaces.

- [Browser bootstrap](https://github.com/johnleshan/tracksimply/blob/master/src/main.jsx): React entry · `src/main.jsx`
- [App shell and routing](https://github.com/johnleshan/tracksimply/blob/master/src/App.jsx): React root · Composes the persistent workspace and selected tool view. · `src/App.jsx`
- [Top navigation](https://github.com/johnleshan/tracksimply/blob/master/src/components/Navbar.jsx): UI component · `src/components/Navbar.jsx`
- [Tool navigation](https://github.com/johnleshan/tracksimply/blob/master/src/components/Sidebar.jsx): UI component · `src/components/Sidebar.jsx`
- [Product detail UI](https://github.com/johnleshan/tracksimply/blob/master/src/components/ProductCard.jsx): UI components · Reusable product cards and modal details. · `src/components/ProductCard.jsx`
- [Dashboard overview](https://github.com/johnleshan/tracksimply/blob/master/src/components/tools/DashboardOverview.jsx): tool view · Aggregates operational data for the dashboard. · `src/components/tools/DashboardOverview.jsx`
- [Account management](https://github.com/johnleshan/tracksimply/blob/master/src/components/tools/AccountManager.jsx): tool view · `src/components/tools/AccountManager.jsx`
- [Finance planning tools](https://github.com/johnleshan/tracksimply/blob/master/src/components/tools/Bookkeeping.jsx): tool views · Bookkeeping, budgets, and debt tracking workspaces. · `src/components/tools/Bookkeeping.jsx`
- [Asset operations tools](https://github.com/johnleshan/tracksimply/blob/master/src/components/tools/InventoryTracker.jsx): tool views · Inventory and vehicle management workspaces. · `src/components/tools/InventoryTracker.jsx`
- [Magic AI UI](https://github.com/johnleshan/tracksimply/blob/master/src/components/MagicAI.jsx): AI component · `src/components/MagicAI.jsx`

### Service boundary

Shared authentication, backend, and AI integrations.

- [Authentication state](https://github.com/johnleshan/tracksimply/blob/master/src/context/AuthContext.jsx): React context · Centralizes signed-in user state for tool views. · `src/context/AuthContext.jsx`
- [Supabase client](https://github.com/johnleshan/tracksimply/blob/master/src/lib/supabase.js): backend client · Browser boundary for authentication and database access. · `src/lib/supabase.js`
- [AI request service](https://github.com/johnleshan/tracksimply/blob/master/src/services/aiService.js): service module · Separates model invocation from AI presentation. · `src/services/aiService.js`
- [Groq provider](https://github.com/johnleshan/tracksimply/blob/master/scratch/test_groq.cjs): external AI provider · Intended or tested model provider. · `scratch/test_groq.cjs`

### Data and operations

Seed data and database setup artifacts.

- [Business CSV data](https://github.com/johnleshan/tracksimply/blob/master/data/budgets.csv): seed/import data · Budgets, debts, inventory, users, and transactions datasets. · `data/budgets.csv`
- [Database initialization](https://github.com/johnleshan/tracksimply/blob/master/scratch/initialize_database.sql): SQL setup · Initializes the Supabase database and its access model. · `scratch/initialize_database.sql`

### Build and deployment

Frontend build, environment, and hosting configuration.

- [Environment contract](https://github.com/johnleshan/tracksimply/blob/master/.env.example): environment template · Defines required Supabase and AI service variables. · `.env.example`
- [Vite build](https://github.com/johnleshan/tracksimply/blob/master/vite.config.js): build configuration · `vite.config.js`
- [Vercel deployment](https://github.com/johnleshan/tracksimply/blob/master/vercel.json): deployment configuration · `vercel.json`

## Connections

- Browser bootstrap → App shell and routing: mounts
- App shell and routing → Top navigation: renders
- App shell and routing → Tool navigation: renders
- Tool navigation → Dashboard overview: selects
- Tool navigation → Account management: selects
- Tool navigation → Finance planning tools: selects
- Tool navigation → Asset operations tools: selects
- App shell and routing → Product detail UI: uses
- App shell and routing → Magic AI UI: renders
- App shell and routing → Authentication state: provides state
- Authentication state → Supabase client: authenticates through
- Dashboard overview → Supabase client: reads operational data
- Account management → Supabase client: manages users
- Finance planning tools → Supabase client: reads and writes records
- Asset operations tools → Supabase client: reads and writes assets
- Magic AI UI → AI request service: delegates requests
- AI request service → Groq provider: invokes model
- Environment contract → Supabase client: supplies configuration
- Environment contract → AI request service: supplies secrets
- Business CSV data → Database initialization: supports import
- Database initialization → Supabase client: initializes
- Vite build → Browser bootstrap: builds
- Vercel deployment → Vite build: deploys build