# srinayan-96/split_shelf architecture

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

- Interactive diagram: https://gitdiagram.com/srinayan-96/split_shelf
- Repository: https://github.com/srinayan-96/split_shelf

## Overview

split_shelf is a shared-household restock tracker. A user signs in, creates or joins a household, then views and updates its shared inventory; purchases feed household history, while restock predictions support reminders. The map includes the client, API/domain services, persistence, and scheduled reminders. Several server routes and domain modules are represented from the SOURCE INDEX rather than inspected excerpts, so uncertain connections are omitted; dashed edges indicate the client/server HTTP boundary, which the excerpts do not show directly.

Main entry points: [`server/src/app.js`](https://github.com/srinayan-96/split_shelf/blob/main/server/src/app.js) (HTTP application), [`server/src/models`](https://github.com/srinayan-96/split_shelf/tree/main/server/src/models) (MongoDB models), [`client/src/App.jsx`](https://github.com/srinayan-96/split_shelf/blob/main/client/src/App.jsx) (Web app routes), [`server/src/routes/household.routes.js`](https://github.com/srinayan-96/split_shelf/blob/main/server/src/routes/household.routes.js) (Household routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Household app"]
  node_webapp["Web app routes<br/>[App.jsx]"]
  node_authui["Sign-in and registration<br/>[Login.jsx]"]
  node_inventoryui["Inventory and item actions<br/>[Home.jsx]"]
  node_historyui["Purchase history<br/>[History.jsx]"]
  node_clientapi["API client<br/>[client.js]"]
  node_itemstate["Inventory state<br/>[useItems.js]"]
end

subgraph group_api["API and domain"]
  node_serverapp["HTTP application<br/>[app.js]"]
  node_householdroutes["Household routes"]
  node_itemroutes["Item routes<br/>[item.routes.js]"]
  node_authroutes["Auth routes<br/>[auth.routes.js]"]
  node_historyroutes["History routes<br/>[history.routes.js]"]
  node_notifroutes["Notification routes"]
  node_jobroutes["Reminder route<br/>[job.routes.js]"]
  node_householdctrl["Household controller"]
  node_itemctrl["Item controller<br/>[item.controller.js]"]
  node_householdsvc["Household service"]
  node_itemsvc["Inventory service<br/>[item.service.js]"]
  node_historysvc["History service<br/>[history.service.js]"]
  node_notifsvc["Notification service"]
end

subgraph group_data["Domain data"]
  node_stores[("MongoDB models")]
end

subgraph group_reminders["Restock reminders"]
  node_restockjob["Reminder scheduler"]
  node_prediction["Restock prediction"]
  node_notifier["Reminder delivery"]
end

node_person(("Household user"))

node_person -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_authui
node_webapp -->|"routes to"| node_inventoryui
node_webapp -->|"routes to"| node_historyui
node_inventoryui -->|"uses"| node_itemstate
node_itemstate -->|"requests through"| node_clientapi
node_authui -.->|"requests through"| node_clientapi
node_historyui -.->|"requests through"| node_clientapi
node_clientapi -.->|"calls API"| node_serverapp
node_serverapp -->|"mounts"| node_householdroutes
node_serverapp -->|"mounts"| node_authroutes
node_serverapp -->|"mounts"| node_notifroutes
node_serverapp -->|"mounts"| node_jobroutes
node_householdroutes -->|"mounts"| node_itemroutes
node_householdroutes -->|"mounts"| node_historyroutes
node_householdroutes -->|"dispatches"| node_householdctrl
node_itemroutes -->|"dispatches"| node_itemctrl
node_householdctrl -->|"delegates to"| node_householdsvc
node_itemctrl -->|"delegates to"| node_itemsvc
node_historyroutes -.->|"dispatches to"| node_historysvc
node_notifroutes -.->|"dispatches to"| node_notifsvc
node_householdsvc -->|"reads and writes"| node_stores
node_itemsvc -->|"reads and writes"| node_stores
node_historysvc -.->|"reads history"| node_stores
node_notifsvc -.->|"accesses"| node_stores
node_jobroutes -->|"runs with lock"| node_restockjob
node_restockjob -->|"predicts restock"| node_prediction
node_restockjob -->|"sends reminders"| node_notifier
node_restockjob -->|"reads inventory"| node_stores

click node_webapp "https://github.com/srinayan-96/split_shelf/blob/main/client/src/App.jsx"
click node_authui "https://github.com/srinayan-96/split_shelf/blob/main/client/src/pages/Login.jsx"
click node_inventoryui "https://github.com/srinayan-96/split_shelf/blob/main/client/src/pages/Home.jsx"
click node_historyui "https://github.com/srinayan-96/split_shelf/blob/main/client/src/pages/History.jsx"
click node_clientapi "https://github.com/srinayan-96/split_shelf/blob/main/client/src/api/client.js"
click node_itemstate "https://github.com/srinayan-96/split_shelf/blob/main/client/src/hooks/useItems.js"
click node_serverapp "https://github.com/srinayan-96/split_shelf/blob/main/server/src/app.js"
click node_householdroutes "https://github.com/srinayan-96/split_shelf/blob/main/server/src/routes/household.routes.js"
click node_itemroutes "https://github.com/srinayan-96/split_shelf/blob/main/server/src/routes/item.routes.js"
click node_authroutes "https://github.com/srinayan-96/split_shelf/blob/main/server/src/routes/auth.routes.js"
click node_historyroutes "https://github.com/srinayan-96/split_shelf/blob/main/server/src/routes/history.routes.js"
click node_notifroutes "https://github.com/srinayan-96/split_shelf/blob/main/server/src/routes/notification.routes.js"
click node_jobroutes "https://github.com/srinayan-96/split_shelf/blob/main/server/src/routes/job.routes.js"
click node_householdctrl "https://github.com/srinayan-96/split_shelf/blob/main/server/src/controllers/household.controller.js"
click node_itemctrl "https://github.com/srinayan-96/split_shelf/blob/main/server/src/controllers/item.controller.js"
click node_householdsvc "https://github.com/srinayan-96/split_shelf/blob/main/server/src/services/household.service.js"
click node_itemsvc "https://github.com/srinayan-96/split_shelf/blob/main/server/src/services/item.service.js"
click node_historysvc "https://github.com/srinayan-96/split_shelf/blob/main/server/src/services/history.service.js"
click node_notifsvc "https://github.com/srinayan-96/split_shelf/blob/main/server/src/services/notification.service.js"
click node_stores "https://github.com/srinayan-96/split_shelf/tree/main/server/src/models"
click node_restockjob "https://github.com/srinayan-96/split_shelf/blob/main/server/src/jobs/restockReminder.job.js"
click node_prediction "https://github.com/srinayan-96/split_shelf/blob/main/server/src/services/prediction.service.js"
click node_notifier "https://github.com/srinayan-96/split_shelf/blob/main/server/src/services/notifier.service.js"

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_webapp,node_authui,node_inventoryui,node_historyui,node_clientapi,node_itemstate,node_person toneBlue
class node_serverapp,node_householdroutes,node_itemroutes,node_authroutes,node_historyroutes,node_notifroutes,node_jobroutes,node_householdctrl,node_itemctrl,node_householdsvc,node_itemsvc,node_historysvc,node_notifsvc toneAmber
class node_stores toneMint
class node_restockjob,node_prediction,node_notifier toneRose
```

## Components

### Household app

- [Web app routes](https://github.com/srinayan-96/split_shelf/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Sign-in and registration](https://github.com/srinayan-96/split_shelf/blob/main/client/src/pages/Login.jsx): `client/src/pages/Login.jsx`
- [Inventory and item actions](https://github.com/srinayan-96/split_shelf/blob/main/client/src/pages/Home.jsx): `client/src/pages/Home.jsx`
- [Purchase history](https://github.com/srinayan-96/split_shelf/blob/main/client/src/pages/History.jsx): `client/src/pages/History.jsx`
- [API client](https://github.com/srinayan-96/split_shelf/blob/main/client/src/api/client.js): `client/src/api/client.js`
- [Inventory state](https://github.com/srinayan-96/split_shelf/blob/main/client/src/hooks/useItems.js): `client/src/hooks/useItems.js`

### API and domain

- [HTTP application](https://github.com/srinayan-96/split_shelf/blob/main/server/src/app.js): `server/src/app.js`
- [Household routes](https://github.com/srinayan-96/split_shelf/blob/main/server/src/routes/household.routes.js): `server/src/routes/household.routes.js`
- [Item routes](https://github.com/srinayan-96/split_shelf/blob/main/server/src/routes/item.routes.js): `server/src/routes/item.routes.js`
- [Auth routes](https://github.com/srinayan-96/split_shelf/blob/main/server/src/routes/auth.routes.js): `server/src/routes/auth.routes.js`
- [History routes](https://github.com/srinayan-96/split_shelf/blob/main/server/src/routes/history.routes.js): `server/src/routes/history.routes.js`
- [Notification routes](https://github.com/srinayan-96/split_shelf/blob/main/server/src/routes/notification.routes.js): `server/src/routes/notification.routes.js`
- [Reminder route](https://github.com/srinayan-96/split_shelf/blob/main/server/src/routes/job.routes.js): `server/src/routes/job.routes.js`
- [Household controller](https://github.com/srinayan-96/split_shelf/blob/main/server/src/controllers/household.controller.js): `server/src/controllers/household.controller.js`
- [Item controller](https://github.com/srinayan-96/split_shelf/blob/main/server/src/controllers/item.controller.js): `server/src/controllers/item.controller.js`
- [Household service](https://github.com/srinayan-96/split_shelf/blob/main/server/src/services/household.service.js): `server/src/services/household.service.js`
- [Inventory service](https://github.com/srinayan-96/split_shelf/blob/main/server/src/services/item.service.js): `server/src/services/item.service.js`
- [History service](https://github.com/srinayan-96/split_shelf/blob/main/server/src/services/history.service.js): `server/src/services/history.service.js`
- [Notification service](https://github.com/srinayan-96/split_shelf/blob/main/server/src/services/notification.service.js): `server/src/services/notification.service.js`

### Domain data

- [MongoDB models](https://github.com/srinayan-96/split_shelf/tree/main/server/src/models): `server/src/models`

### Restock reminders

- [Reminder scheduler](https://github.com/srinayan-96/split_shelf/blob/main/server/src/jobs/restockReminder.job.js): `server/src/jobs/restockReminder.job.js`
- [Restock prediction](https://github.com/srinayan-96/split_shelf/blob/main/server/src/services/prediction.service.js): `server/src/services/prediction.service.js`
- [Reminder delivery](https://github.com/srinayan-96/split_shelf/blob/main/server/src/services/notifier.service.js): `server/src/services/notifier.service.js`

### Other components

- **Household user**

## Connections

- Household user → Web app routes: uses (evidence: `client/src/App.jsx`)
- Web app routes → Sign-in and registration: routes to (evidence: `client/src/App.jsx`)
- Web app routes → Inventory and item actions: routes to (evidence: `client/src/App.jsx`)
- Web app routes → Purchase history: routes to (evidence: `client/src/App.jsx`)
- Inventory and item actions → Inventory state: uses (evidence: `client/src/pages/Home.jsx`)
- Inventory state → API client: requests through (evidence: `client/src/hooks/useItems.js`)
- Sign-in and registration → API client: requests through
- Purchase history → API client: requests through (evidence: `client/src/pages/History.jsx`)
- API client → HTTP application: calls API
- HTTP application → Household routes: mounts (evidence: `server/src/app.js`)
- HTTP application → Auth routes: mounts (evidence: `server/src/app.js`)
- HTTP application → Notification routes: mounts (evidence: `server/src/app.js`)
- HTTP application → Reminder route: mounts (evidence: `server/src/app.js`)
- Household routes → Item routes: mounts (evidence: `server/src/routes/household.routes.js`)
- Household routes → History routes: mounts (evidence: `server/src/routes/household.routes.js`)
- Household routes → Household controller: dispatches (evidence: `server/src/routes/household.routes.js`)
- Item routes → Item controller: dispatches (evidence: `server/src/routes/item.routes.js`)
- Household controller → Household service: delegates to (evidence: `server/src/controllers/household.controller.js`)
- Item controller → Inventory service: delegates to (evidence: `server/src/controllers/item.controller.js`)
- History routes → History service: dispatches to
- Notification routes → Notification service: dispatches to
- Household service → MongoDB models: reads and writes (evidence: `server/src/services/household.service.js`)
- Inventory service → MongoDB models: reads and writes (evidence: `server/src/services/item.service.js`)
- History service → MongoDB models: reads history
- Notification service → MongoDB models: accesses
- Reminder route → Reminder scheduler: runs with lock (evidence: `server/src/routes/job.routes.js`)
- Reminder scheduler → Restock prediction: predicts restock (evidence: `server/src/jobs/restockReminder.job.js`)
- Reminder scheduler → Reminder delivery: sends reminders (evidence: `server/src/jobs/restockReminder.job.js`)
- Reminder scheduler → MongoDB models: reads inventory (evidence: `server/src/jobs/restockReminder.job.js`)