# ankit-iiitkota/billbuddy architecture

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

- Interactive diagram: https://gitdiagram.com/ankit-iiitkota/billbuddy
- Repository: https://github.com/ankit-iiitkota/billbuddy

## Overview

BillBuddy is a real-time expense-splitting app: users authenticate, create groups or track expenses with individuals, record split details, and review balances and settlements. The dashboard and group/person views present spending and debt state; Convex provides the backend and database. Scheduled reminders and spending insights are represented from the documented Inngest modules and route imports, but their full execution flow was not inspected. The graph emphasizes evidenced UI calls and documented capabilities; unsampled backend relationships are left out where wiring is uncertain.

Main entry points: [`app/(main)/groups/[id]/page.jsx`](https://github.com/ankit-iiitkota/billbuddy/blob/main/app/(main)/groups/%5Bid%5D/page.jsx) (Group details), [`hooks/use-convex-query.js`](https://github.com/ankit-iiitkota/billbuddy/blob/main/hooks/use-convex-query.js) (Convex query hooks), [`convex/schema.js`](https://github.com/ankit-iiitkota/billbuddy/blob/main/convex/schema.js) (Convex database), [`app/(main)/person/[id]/page.jsx`](https://github.com/ankit-iiitkota/billbuddy/blob/main/app/(main)/person/%5Bid%5D/page.jsx) (Person details)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_auth["Authentication<br/>[page.jsx]"]
  node_landing["Landing page<br/>[page.jsx]"]
  node_dashboard["Dashboard<br/>[page.jsx]"]
  node_contacts["Contacts and groups<br/>[page.jsx]"]
end

subgraph group_expense_domain["Expense domain"]
  node_expense_form["Expense entry<br/>[expense-form.jsx]"]
  node_group_view["Group details<br/>[page.jsx]"]
  node_person_view["Person details<br/>[page.jsx]"]
  node_settlement["Settlement entry"]
  node_expense_list["Expense list<br/>[expense-list.jsx]"]
  node_settlement_list["Settlement list"]
  node_group_balances["Group balances<br/>[group-balances.jsx]"]
end

subgraph group_backend["Convex backend"]
  node_query_hook["Convex query hooks"]
  node_convex["Convex functions<br/>[expenses.js]"]
  node_groups_api["Group functions<br/>[groups.js]"]
  node_dashboard_api["Dashboard functions<br/>[dashboard.js]"]
  node_settlement_api["Settlement functions<br/>[settlements.js]"]
  node_contacts_api["Contact functions<br/>[contacts.js]"]
  node_database[("Convex database<br/>[schema.js]")]
end

subgraph group_automation["Automation"]
  node_inngest_route["Inngest endpoint<br/>[route.js]"]
  node_reminders["Payment reminders"]
  node_insights["Spending insights"]
end

node_user(("User"))
node_inngest{{"Inngest service"}}
node_clerk{{"Clerk auth"}}

node_user -->|"visits"| node_landing
node_user -->|"authenticates"| node_auth
node_auth -.->|"authenticates with"| node_clerk
node_user -->|"tracks spending"| node_dashboard
node_dashboard -->|"queries through"| node_query_hook
node_dashboard -->|"requests summaries"| node_dashboard_api
node_contacts -->|"queries through"| node_query_hook
node_contacts -.->|"manages contacts"| node_contacts_api
node_user -->|"enters expense"| node_expense_form
node_expense_form -->|"submits through"| node_query_hook
node_expense_form -->|"records expense"| node_convex
node_group_view -->|"queries through"| node_query_hook
node_group_view -->|"loads group data"| node_groups_api
node_group_view -->|"renders balances"| node_group_balances
node_group_view -->|"renders expenses"| node_expense_list
node_group_view -->|"renders settlements"| node_settlement_list
node_person_view -->|"queries through"| node_query_hook
node_person_view -->|"renders expenses"| node_expense_list
node_person_view -->|"renders settlements"| node_settlement_list
node_user -->|"records payment"| node_settlement
node_settlement -.->|"submits through"| node_query_hook
node_convex -.->|"reads and writes"| node_database
node_groups_api -.->|"reads and writes"| node_database
node_dashboard_api -.->|"reads"| node_database
node_settlement_api -.->|"reads and writes"| node_database
node_contacts_api -.->|"reads and writes"| node_database
node_inngest_route -->|"registers"| node_reminders
node_inngest_route -->|"registers"| node_insights
node_reminders -.->|"runs on"| node_inngest
node_insights -.->|"runs on"| node_inngest

click node_auth "https://github.com/ankit-iiitkota/billbuddy/blob/main/app/(auth)/sign-in/%5B%5B...signIn%5D%5D/page.jsx"
click node_landing "https://github.com/ankit-iiitkota/billbuddy/blob/main/app/page.jsx"
click node_dashboard "https://github.com/ankit-iiitkota/billbuddy/blob/main/app/(main)/dashboard/page.jsx"
click node_contacts "https://github.com/ankit-iiitkota/billbuddy/blob/main/app/(main)/contacts/page.jsx"
click node_expense_form "https://github.com/ankit-iiitkota/billbuddy/blob/main/app/(main)/expenses/new/components/expense-form.jsx"
click node_group_view "https://github.com/ankit-iiitkota/billbuddy/blob/main/app/(main)/groups/%5Bid%5D/page.jsx"
click node_person_view "https://github.com/ankit-iiitkota/billbuddy/blob/main/app/(main)/person/%5Bid%5D/page.jsx"
click node_settlement "https://github.com/ankit-iiitkota/billbuddy/blob/main/app/(main)/settlements/%5Btype%5D/%5Bid%5D/components/settlement-form.jsx"
click node_expense_list "https://github.com/ankit-iiitkota/billbuddy/blob/main/components/expense-list.jsx"
click node_settlement_list "https://github.com/ankit-iiitkota/billbuddy/blob/main/components/settlement-list.jsx"
click node_group_balances "https://github.com/ankit-iiitkota/billbuddy/blob/main/components/group-balances.jsx"
click node_query_hook "https://github.com/ankit-iiitkota/billbuddy/blob/main/hooks/use-convex-query.js"
click node_convex "https://github.com/ankit-iiitkota/billbuddy/blob/main/convex/expenses.js"
click node_groups_api "https://github.com/ankit-iiitkota/billbuddy/blob/main/convex/groups.js"
click node_dashboard_api "https://github.com/ankit-iiitkota/billbuddy/blob/main/convex/dashboard.js"
click node_settlement_api "https://github.com/ankit-iiitkota/billbuddy/blob/main/convex/settlements.js"
click node_contacts_api "https://github.com/ankit-iiitkota/billbuddy/blob/main/convex/contacts.js"
click node_database "https://github.com/ankit-iiitkota/billbuddy/blob/main/convex/schema.js"
click node_inngest_route "https://github.com/ankit-iiitkota/billbuddy/blob/main/app/api/inngest/route.js"
click node_reminders "https://github.com/ankit-iiitkota/billbuddy/blob/main/lib/inngest/payment-reminders.js"
click node_insights "https://github.com/ankit-iiitkota/billbuddy/blob/main/lib/inngest/spending-insights.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_auth,node_landing,node_dashboard,node_contacts,node_user toneBlue
class node_expense_form,node_group_view,node_person_view,node_settlement,node_expense_list,node_settlement_list,node_group_balances toneAmber
class node_query_hook,node_convex,node_groups_api,node_dashboard_api,node_settlement_api,node_contacts_api,node_database toneMint
class node_inngest_route,node_reminders,node_insights toneRose
class node_inngest,node_clerk toneIndigo
```

## Components

### User experience

- [Authentication](https://github.com/ankit-iiitkota/billbuddy/blob/main/app/(auth)/sign-in/%5B%5B...signIn%5D%5D/page.jsx): `app/(auth)/sign-in/[[...signIn]]/page.jsx`
- [Landing page](https://github.com/ankit-iiitkota/billbuddy/blob/main/app/page.jsx): `app/page.jsx`
- [Dashboard](https://github.com/ankit-iiitkota/billbuddy/blob/main/app/(main)/dashboard/page.jsx): `app/(main)/dashboard/page.jsx`
- [Contacts and groups](https://github.com/ankit-iiitkota/billbuddy/blob/main/app/(main)/contacts/page.jsx): `app/(main)/contacts/page.jsx`

### Expense domain

- [Expense entry](https://github.com/ankit-iiitkota/billbuddy/blob/main/app/(main)/expenses/new/components/expense-form.jsx): `app/(main)/expenses/new/components/expense-form.jsx`
- [Group details](https://github.com/ankit-iiitkota/billbuddy/blob/main/app/(main)/groups/%5Bid%5D/page.jsx): `app/(main)/groups/[id]/page.jsx`
- [Person details](https://github.com/ankit-iiitkota/billbuddy/blob/main/app/(main)/person/%5Bid%5D/page.jsx): `app/(main)/person/[id]/page.jsx`
- [Settlement entry](https://github.com/ankit-iiitkota/billbuddy/blob/main/app/(main)/settlements/%5Btype%5D/%5Bid%5D/components/settlement-form.jsx): `app/(main)/settlements/[type]/[id]/components/settlement-form.jsx`
- [Expense list](https://github.com/ankit-iiitkota/billbuddy/blob/main/components/expense-list.jsx): `components/expense-list.jsx`
- [Settlement list](https://github.com/ankit-iiitkota/billbuddy/blob/main/components/settlement-list.jsx): `components/settlement-list.jsx`
- [Group balances](https://github.com/ankit-iiitkota/billbuddy/blob/main/components/group-balances.jsx): `components/group-balances.jsx`

### Convex backend

- [Convex query hooks](https://github.com/ankit-iiitkota/billbuddy/blob/main/hooks/use-convex-query.js): `hooks/use-convex-query.js`
- [Convex functions](https://github.com/ankit-iiitkota/billbuddy/blob/main/convex/expenses.js): `convex/expenses.js`
- [Group functions](https://github.com/ankit-iiitkota/billbuddy/blob/main/convex/groups.js): `convex/groups.js`
- [Dashboard functions](https://github.com/ankit-iiitkota/billbuddy/blob/main/convex/dashboard.js): `convex/dashboard.js`
- [Settlement functions](https://github.com/ankit-iiitkota/billbuddy/blob/main/convex/settlements.js): `convex/settlements.js`
- [Contact functions](https://github.com/ankit-iiitkota/billbuddy/blob/main/convex/contacts.js): `convex/contacts.js`
- [Convex database](https://github.com/ankit-iiitkota/billbuddy/blob/main/convex/schema.js): `convex/schema.js`

### Automation

- [Inngest endpoint](https://github.com/ankit-iiitkota/billbuddy/blob/main/app/api/inngest/route.js): `app/api/inngest/route.js`
- [Payment reminders](https://github.com/ankit-iiitkota/billbuddy/blob/main/lib/inngest/payment-reminders.js): `lib/inngest/payment-reminders.js`
- [Spending insights](https://github.com/ankit-iiitkota/billbuddy/blob/main/lib/inngest/spending-insights.js): `lib/inngest/spending-insights.js`

### Other components

- **User**
- **Inngest service**
- **Clerk auth**

## Connections

- User → Landing page: visits (evidence: `README.md`)
- User → Authentication: authenticates (evidence: `README.md`)
- Authentication → Clerk auth: authenticates with (evidence: `README.md`)
- User → Dashboard: tracks spending (evidence: `README.md`)
- Dashboard → Convex query hooks: queries through (evidence: `app/(main)/dashboard/page.jsx`)
- Dashboard → Dashboard functions: requests summaries (evidence: `app/(main)/dashboard/page.jsx`)
- Contacts and groups → Convex query hooks: queries through (evidence: `app/(main)/contacts/page.jsx`)
- Contacts and groups → Contact functions: manages contacts (evidence: `app/(main)/contacts/page.jsx`)
- User → Expense entry: enters expense (evidence: `README.md`)
- Expense entry → Convex query hooks: submits through (evidence: `app/(main)/expenses/new/components/expense-form.jsx`)
- Expense entry → Convex functions: records expense (evidence: `app/(main)/expenses/new/components/expense-form.jsx`)
- Group details → Convex query hooks: queries through (evidence: `app/(main)/groups/[id]/page.jsx`)
- Group details → Group functions: loads group data (evidence: `app/(main)/groups/[id]/page.jsx`)
- Group details → Group balances: renders balances (evidence: `app/(main)/groups/[id]/page.jsx`)
- Group details → Expense list: renders expenses (evidence: `app/(main)/groups/[id]/page.jsx`)
- Group details → Settlement list: renders settlements (evidence: `app/(main)/groups/[id]/page.jsx`)
- Person details → Convex query hooks: queries through (evidence: `app/(main)/person/[id]/page.jsx`)
- Person details → Expense list: renders expenses (evidence: `app/(main)/person/[id]/page.jsx`)
- Person details → Settlement list: renders settlements (evidence: `app/(main)/person/[id]/page.jsx`)
- User → Settlement entry: records payment (evidence: `README.md`)
- Settlement entry → Convex query hooks: submits through (evidence: `app/(main)/settlements/[type]/[id]/components/settlement-form.jsx`)
- Convex functions → Convex database: reads and writes
- Group functions → Convex database: reads and writes
- Dashboard functions → Convex database: reads
- Settlement functions → Convex database: reads and writes
- Contact functions → Convex database: reads and writes
- Inngest endpoint → Payment reminders: registers (evidence: `app/api/inngest/route.js`)
- Inngest endpoint → Spending insights: registers (evidence: `app/api/inngest/route.js`)
- Payment reminders → Inngest service: runs on
- Spending insights → Inngest service: runs on
