# justtvikram/inventory-attendance architecture

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

- Interactive diagram: https://gitdiagram.com/justtvikram/inventory-attendance
- Repository: https://github.com/justtvikram/inventory-attendance

## Overview

1. **High-level shape**
   - This is a **cross-platform mobile app** built with **Expo + React Native + TypeScript**.
   - The app is split into a **client-side UI** and a **Supabase-backed data layer**. There is no custom server in the repo; Supabase provides **Auth, Postgres, and Row Level Security**.

2. **App shell and navigation**
   - The `src/app` folder uses **expo-router** file-based routing.
   - `src/app/_layout.tsx` is the root composition point: it wires up app-wide providers and the **auth gate**.
   - The main experience is organized into a **tab navigator** under `src/app/(tabs)` for:
     - Dashboard (`index.tsx`)
     - Inventory (`inventory.tsx`)
     - Attendance (`attendance.tsx`)
   - Additional routed screens exist for:
     - Login (`login.tsx`)
     - Employee list (`employees.tsx`)
     - Employee detail (`employee/[id].tsx`)
     - Product detail (`product/[id].tsx`)

3. **Authentication boundary**
   - Authentication is handled entirely by **Supabase Auth**.
   - `src/lib/auth.tsx` exposes an `AuthProvider` / `useAuth()` style context so the rest of the app can treat auth state as a shared dependency.
   - The root layout likely redirects unauthenticated users to `login.tsx`, while signed-in users enter the main tab flow.
   - The app is **single-user by design**, but the actual security boundary is still enforced server-side by row ownership.

4. **Data access pattern**
   - Server state is managed with **@tanstack/react-query**.
   - Feature-specific query modules live in `src/lib/queries/`:
     - `products.ts`
     - `employees.ts`
     - `attendance.ts`
     - `profiles.ts`
   - These modules are the main boundary between UI screens and Supabase calls, centralizing fetch/mutation logic and cache behavior.

5. **Core domain subsystems**
   - **Dashboard**: surfaces summary counts and low-stock alerts.
   - **Inventory**: product CRUD plus stock adjustments.
   - **Employees**: manage the roster and view individual employee records.
   - **Attendance**: mark daily attendance and review attendance history.
   - These are user-facing feature areas, but they all share the same backend model and auth scope.

6. **Inventory-specific flow**
   - Inventory is the most transactional subsystem.
   - `src/components/stock-adjust-dialog.tsx` is a shared interaction component for changing stock.
   - The README notes that stock changes are done through an **atomic RPC**: quantity update and movement logging happen together.
   - This means the UI does not directly “just edit a number”; it calls into a backend operation that preserves consistency and auditability.

7. **Shared domain model**
   - `src/lib/types.ts` mirrors the database row types used across the app.
   - Domain constants/utilities such as:
     - `attendance-status.ts`
     - `stock-reason.ts`
     - `units.ts`
   - These files indicate the app uses a small, explicit set of domain enums and display mappings rather than ad hoc strings scattered through screens.

8. **Backend schema and security**
   - The `supabase/` directory is the backend source of truth:
     - `schema.sql`
     - `migrations/`
   - The database is secured with **Row Level Security**, scoped by `owner_id = auth.uid()`.
   - This is the key boundary in the architecture: the client can only read/write rows owned by the signed-in account.
   - The schema also includes the RPC used for inventory movement, which is important for drawing the backend as more than just CRUD tables.

9. **Session persistence and client setup**
   - `src/lib/supabase.ts` configures the Supabase client.
   - The README indicates the auth session is persisted with **AsyncStorage**, so sessions survive app restarts on mobile.
   - That makes the data flow: app start → restore session locally → confirm auth state with Supabase → render gated routes or login.

10. **UI system and presentation**
   - The app uses **react-native-paper** for the Material Design component layer.
   - `src/theme/` holds the shared theme configuration, which likely feeds the Paper provider in the root layout.
   - `src/components/` contains reusable UI pieces shared across feature screens, while the route files stay focused on screen composition.

11. **Build and deployment boundaries**
   - Tooling is standard Expo mobile tooling: **Metro**, **Babel**, and **EAS Build**.
   - `eas.json` defines installable build profiles for Android/iOS.
   - `app.json`, `metro.config.js`, `babel.config.js`, and `scripts/reset-project.js` support the app runtime and development workflow, but they do not change the core architecture.

12. **How the system behaves end-to-end**
   - A signed-in user opens the app.
   - The root layout restores auth state and routes into the tab shell.
   - Screens call React Query hooks, which call Supabase.
   - Supabase enforces ownership via RLS and returns data.
   - Inventory mutations may go through the stock RPC to keep the product quantity and movement log in sync.
   - UI updates are reflected through React Query cache updates and invalidations.

Main entry points: [`src/lib/queries/products.ts`](https://github.com/justtvikram/inventory-attendance/blob/main/src/lib/queries/products.ts) (Products queries), [`src/lib/supabase.ts`](https://github.com/justtvikram/inventory-attendance/blob/main/src/lib/supabase.ts) (Supabase client), [`src/lib/types.ts`](https://github.com/justtvikram/inventory-attendance/blob/main/src/lib/types.ts) (Domain types), [`src/app/_layout.tsx`](https://github.com/justtvikram/inventory-attendance/blob/main/src/app/_layout.tsx) (Root layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Shell"]
  node_root_layout["Root layout<br/>expo-router entry<br/>[_layout.tsx]"]
  node_tabs_layout["Tab layout<br/>tab navigator<br/>[_layout.tsx]"]
  node_login_screen["Login<br/>auth screen<br/>[login.tsx]"]
end

subgraph group_features["Features"]
  node_dashboard_screen["Dashboard<br/>summary screen<br/>[index.tsx]"]
  node_inventory_screen["Inventory<br/>[inventory.tsx]"]
  node_attendance_screen["Attendance<br/>[attendance.tsx]"]
  node_employees_screen["Employees<br/>roster screen<br/>[employees.tsx]"]
  node_employee_detail["Employee detail<br/>detail screen<br/>[[id].tsx]"]
  node_product_detail["Product detail<br/>detail screen<br/>[[id].tsx]"]
end

subgraph group_data["Data Layer"]
  node_auth_context(("Auth context<br/>client auth<br/>[auth.tsx]"))
  node_supabase_client[("Supabase client<br/>client setup<br/>[supabase.ts]")]
  node_products_queries["Products queries<br/>query module<br/>[products.ts]"]
  node_employees_queries["Employees queries<br/>query module<br/>[employees.ts]"]
  node_attendance_queries["Attendance queries<br/>query module<br/>[attendance.ts]"]
  node_profiles_queries["Profiles queries<br/>query module<br/>[profiles.ts]"]
  node_domain_types["Domain types<br/>shared types<br/>[types.ts]"]
end

subgraph group_backend["Supabase Backend"]
  node_schema[("Schema<br/>[schema.sql]")]
  node_migrations["Migrations"]
end

subgraph group_ui["Shared UI"]
  node_stock_dialog["Stock dialog<br/>ui component"]
  node_unit_dropdown["Unit dropdown<br/>ui component<br/>[unit-dropdown.tsx]"]
  node_theme["Theme<br/>[index.ts]"]
end

node_root_layout -->|"provides auth"| node_auth_context
node_root_layout -->|"provides theme"| node_theme
node_root_layout -->|"routes signed-in"| node_tabs_layout
node_root_layout -->|"redirects to"| node_login_screen
node_tabs_layout -->|"tab"| node_dashboard_screen
node_tabs_layout -->|"tab"| node_inventory_screen
node_tabs_layout -->|"tab"| node_attendance_screen
node_dashboard_screen -->|"reads"| node_products_queries
node_inventory_screen -->|"reads/writes"| node_products_queries
node_inventory_screen -->|"uses"| node_stock_dialog
node_stock_dialog -->|"mutates"| node_products_queries
node_attendance_screen -->|"reads/writes"| node_attendance_queries
node_employees_screen -->|"reads/writes"| node_employees_queries
node_employees_screen -->|"navigates to"| node_employee_detail
node_inventory_screen -->|"navigates to"| node_product_detail
node_product_detail -->|"reads/writes"| node_products_queries
node_product_detail -->|"uses"| node_stock_dialog
node_products_queries -->|"calls"| node_supabase_client
node_employees_queries -->|"calls"| node_supabase_client
node_attendance_queries -->|"calls"| node_supabase_client
node_profiles_queries -->|"calls"| node_supabase_client
node_supabase_client -->|"targets"| node_schema
node_schema -.->|"evolves via"| node_migrations
node_schema -.->|"mirrors"| node_domain_types
node_products_queries -->|"uses"| node_domain_types
node_employees_queries -->|"uses"| node_domain_types
node_attendance_queries -->|"uses"| node_domain_types
node_profiles_queries -->|"uses"| node_domain_types
node_products_queries -.->|"RPC/RLS constrained"| node_schema

click node_root_layout "https://github.com/justtvikram/inventory-attendance/blob/main/src/app/_layout.tsx"
click node_tabs_layout "https://github.com/justtvikram/inventory-attendance/blob/main/src/app/(tabs)/_layout.tsx"
click node_login_screen "https://github.com/justtvikram/inventory-attendance/blob/main/src/app/login.tsx"
click node_dashboard_screen "https://github.com/justtvikram/inventory-attendance/blob/main/src/app/(tabs)/index.tsx"
click node_inventory_screen "https://github.com/justtvikram/inventory-attendance/blob/main/src/app/(tabs)/inventory.tsx"
click node_attendance_screen "https://github.com/justtvikram/inventory-attendance/blob/main/src/app/(tabs)/attendance.tsx"
click node_employees_screen "https://github.com/justtvikram/inventory-attendance/blob/main/src/app/employees.tsx"
click node_employee_detail "https://github.com/justtvikram/inventory-attendance/blob/main/src/app/employee/[id].tsx"
click node_product_detail "https://github.com/justtvikram/inventory-attendance/blob/main/src/app/product/[id].tsx"
click node_auth_context "https://github.com/justtvikram/inventory-attendance/blob/main/src/lib/auth.tsx"
click node_supabase_client "https://github.com/justtvikram/inventory-attendance/blob/main/src/lib/supabase.ts"
click node_products_queries "https://github.com/justtvikram/inventory-attendance/blob/main/src/lib/queries/products.ts"
click node_employees_queries "https://github.com/justtvikram/inventory-attendance/blob/main/src/lib/queries/employees.ts"
click node_attendance_queries "https://github.com/justtvikram/inventory-attendance/blob/main/src/lib/queries/attendance.ts"
click node_profiles_queries "https://github.com/justtvikram/inventory-attendance/blob/main/src/lib/queries/profiles.ts"
click node_domain_types "https://github.com/justtvikram/inventory-attendance/blob/main/src/lib/types.ts"
click node_stock_dialog "https://github.com/justtvikram/inventory-attendance/blob/main/src/components/stock-adjust-dialog.tsx"
click node_unit_dropdown "https://github.com/justtvikram/inventory-attendance/blob/main/src/components/unit-dropdown.tsx"
click node_theme "https://github.com/justtvikram/inventory-attendance/blob/main/src/theme/index.ts"
click node_schema "https://github.com/justtvikram/inventory-attendance/blob/main/supabase/schema.sql"
click node_migrations "https://github.com/justtvikram/inventory-attendance/blob/main/supabase/migrations/20260624103606_baseline_schema.sql"

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_root_layout,node_tabs_layout,node_login_screen toneBlue
class node_dashboard_screen,node_inventory_screen,node_attendance_screen,node_employees_screen,node_employee_detail,node_product_detail toneAmber
class node_auth_context,node_supabase_client,node_products_queries,node_employees_queries,node_attendance_queries,node_profiles_queries,node_domain_types toneMint
class node_schema,node_migrations toneRose
class node_stock_dialog,node_unit_dropdown,node_theme toneIndigo
```

## Components

### App Shell

Expo Router composition, navigation, and route entry points.

- [Root layout](https://github.com/justtvikram/inventory-attendance/blob/main/src/app/_layout.tsx): expo-router entry · Composes providers and the auth gate for the app. · `src/app/_layout.tsx`
- [Tab layout](https://github.com/justtvikram/inventory-attendance/blob/main/src/app/(tabs)/_layout.tsx): tab navigator · Defines the authenticated tab shell. · `src/app/(tabs)/_layout.tsx`
- [Login](https://github.com/justtvikram/inventory-attendance/blob/main/src/app/login.tsx): auth screen · Unauthenticated entry screen. · `src/app/login.tsx`

### Features

User-facing domain areas built on shared data access.

- [Dashboard](https://github.com/justtvikram/inventory-attendance/blob/main/src/app/(tabs)/index.tsx): summary screen · Shows counts and low-stock highlights. · `src/app/(tabs)/index.tsx`
- [Inventory](https://github.com/justtvikram/inventory-attendance/blob/main/src/app/(tabs)/inventory.tsx): inventory screen · Product list and stock operations. · `src/app/(tabs)/inventory.tsx`
- [Attendance](https://github.com/justtvikram/inventory-attendance/blob/main/src/app/(tabs)/attendance.tsx): attendance screen · Daily attendance entry and history. · `src/app/(tabs)/attendance.tsx`
- [Employees](https://github.com/justtvikram/inventory-attendance/blob/main/src/app/employees.tsx): roster screen · Lists employees and opens records. · `src/app/employees.tsx`
- [Employee detail](https://github.com/justtvikram/inventory-attendance/blob/main/src/app/employee/[id].tsx): detail screen · Shows one employee record. · `src/app/employee/[id].tsx`
- [Product detail](https://github.com/justtvikram/inventory-attendance/blob/main/src/app/product/[id].tsx): detail screen · Shows one product record and stock actions. · `src/app/product/[id].tsx`

### Data Layer

Auth, queries, and shared domain types used by screens.

- [Auth context](https://github.com/justtvikram/inventory-attendance/blob/main/src/lib/auth.tsx): client auth · Shared auth state and helpers for the app. · `src/lib/auth.tsx`
- [Supabase client](https://github.com/justtvikram/inventory-attendance/blob/main/src/lib/supabase.ts): client setup · Configures the Supabase connection and session storage. · `src/lib/supabase.ts`
- [Products queries](https://github.com/justtvikram/inventory-attendance/blob/main/src/lib/queries/products.ts): query module · Fetches and mutates product data. · `src/lib/queries/products.ts`
- [Employees queries](https://github.com/justtvikram/inventory-attendance/blob/main/src/lib/queries/employees.ts): query module · Fetches and mutates employee data. · `src/lib/queries/employees.ts`
- [Attendance queries](https://github.com/justtvikram/inventory-attendance/blob/main/src/lib/queries/attendance.ts): query module · Fetches and mutates attendance data. · `src/lib/queries/attendance.ts`
- [Profiles queries](https://github.com/justtvikram/inventory-attendance/blob/main/src/lib/queries/profiles.ts): query module · Loads user profile data used by the app shell. · `src/lib/queries/profiles.ts`
- [Domain types](https://github.com/justtvikram/inventory-attendance/blob/main/src/lib/types.ts): shared types · Row-shaped types mirrored from the database. · `src/lib/types.ts`

### Supabase Backend

Database schema, migrations, and security boundary.

- [Schema](https://github.com/justtvikram/inventory-attendance/blob/main/supabase/schema.sql): database schema · Source-of-truth tables, RPCs, and RLS rules. · `supabase/schema.sql`
- [Migrations](https://github.com/justtvikram/inventory-attendance/blob/main/supabase/migrations/20260624103606_baseline_schema.sql): db migrations · Schema evolution history for Supabase. · `supabase/migrations/20260624103606_baseline_schema.sql`

### Shared UI

Reusable components and theme primitives.

- [Stock dialog](https://github.com/justtvikram/inventory-attendance/blob/main/src/components/stock-adjust-dialog.tsx): ui component · Shared stock adjustment interaction. · `src/components/stock-adjust-dialog.tsx`
- [Unit dropdown](https://github.com/justtvikram/inventory-attendance/blob/main/src/components/unit-dropdown.tsx): ui component · Reusable unit selection control. · `src/components/unit-dropdown.tsx`
- [Theme](https://github.com/justtvikram/inventory-attendance/blob/main/src/theme/index.ts): paper theme · Shared visual theme for the app. · `src/theme/index.ts`

## Connections

- Root layout → Auth context: provides auth · Root composition exposes auth state to the app.
- Root layout → Theme: provides theme · App-wide UI theme is mounted at the root.
- Root layout → Tab layout: routes signed-in · Authenticated users enter the main tab shell.
- Root layout → Login: redirects to · Unauthenticated users go to login.
- Tab layout → Dashboard: tab · Dashboard is one of the primary tabs.
- Tab layout → Inventory: tab · Inventory is one of the primary tabs.
- Tab layout → Attendance: tab · Attendance is one of the primary tabs.
- Dashboard → Products queries: reads · Dashboard summary uses product and stock data.
- Inventory → Products queries: reads/writes · Inventory drives product CRUD and stock updates.
- Inventory → Stock dialog: uses · Stock adjustments are performed through the shared dialog.
- Stock dialog → Products queries: mutates · Dialog triggers stock movement operations.
- Attendance → Attendance queries: reads/writes · Attendance screen uses the attendance query layer.
- Employees → Employees queries: reads/writes · Roster management is handled through employee queries.
- Employees → Employee detail: navigates to · List screen opens the detail route.
- Inventory → Product detail: navigates to · Inventory opens product detail views.
- Product detail → Products queries: reads/writes · Detail screen loads and updates the product record.
- Product detail → Stock dialog: uses · Detail screen reuses the stock adjustment flow.
- Products queries → Supabase client: calls · Product data is fetched through the Supabase client.
- Employees queries → Supabase client: calls · Employee data is fetched through the Supabase client.
- Attendance queries → Supabase client: calls · Attendance data is fetched through the Supabase client.
- Profiles queries → Supabase client: calls · Profile data is fetched through the Supabase client.
- Supabase client → Schema: targets · Client talks to the Supabase-backed database and auth.
- Schema → Migrations: evolves via · Migrations define and update the schema.
- Schema → Domain types: mirrors · App types reflect database row shapes.
- Products queries → Domain types: uses · Query modules share domain row types.
- Employees queries → Domain types: uses · Query modules share domain row types.
- Attendance queries → Domain types: uses · Query modules share domain row types.
- Profiles queries → Domain types: uses · Query modules share domain row types.
- Products queries → Schema: RPC/RLS constrained · Inventory mutations rely on backend atomic operations and ownership rules.