# kavya-hjb217/xpnsone architecture

> Architecture diagram of the GitHub repository kavya-hjb217/xpnsone, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kavya-hjb217/xpnsone
- Repository: https://github.com/kavya-hjb217/xpnsone

## Overview

##### Project Type and Purpose
- This is a full-stack web application built on Next.js 13+ (app router), leveraging Convex as a hosted backend (data store + serverless functions) and Inngest for background jobs/cron-style workflows. The UI is composed of React components (pages, nested layouts, shared UI library), and the business logic/data access lives in Convex functions and Inngest tasks.

##### File Structure
- app/
- Contains Next.js app router pages & layouts split into two route segments:
– (auth): sign-in & sign-up flows
– (main): protected routes (dashboard, contacts, expenses, groups, person, settlements)
- app/api/inngest/route.js: HTTP endpoint for Inngest webhooks
- app/globals.css, app/layout.js: global styles & root layout
- components/
- Reusable UI components (e.g., header, expense-list)
- components/ui: atomic primitives (buttons, dialogs, inputs)
- convex/
- Convex schema & server functions (users.js, expenses.js, groups.js, settlements.js, etc.)
- Convex client config & generated types
- lib/
- Inngest client setup & job definitions (payment-reminders, spending-insights)
- Utility modules
- hooks/
- Custom React hooks for accessing Convex data and user store
- next.config.mjs, middleware.js, postcss.config.mjs, tsconfig/jsconfig, ESLint configs, etc.
- public/: static assets (logos, testimonials)

##### Main Components & Relationships
a. Frontend (Browser → Next.js SSR/SSG/Client-side)
– Pages under app/(auth) & app/(main)
– React components & shared UI library
– Uses use-convex-query hook to fetch/update data
b. Backend API – Convex
– Convex serverless functions (CRUD on users, groups, expenses, contacts, settlements)
– Data stored in Convex’s managed database
– Accessed via convex-client-provider in React
c. Background Jobs & Workflows – Inngest
– Defined in lib/inngest/*.js
– Triggered via HTTP webhook at app/api/inngest/route.js or via Convex triggers
– Jobs: payment-reminders (emails), spending-insights reports
– External email service integration in convex/email.js or lib/inngest
d. External Services
– Email provider (SMTP or transactional API)
– (Optionally) analytics, logging, third-party auth if configured

##### Architectural Patterns and Design Principles
- Component-based UI (Next.js app router + nested layouts)
- Serverless backend (Convex functions) decoupled from UI
- Event-driven background processing (Inngest workflows)
- Separation of concerns: UI vs. business logic vs. data access vs. cron jobs
- Hooks for encapsulating data layer (React Query–style via Convex)

##### Elements
- Clear labels: Browser, Next.js Frontend (Routing & React Components), Convex Backend, Inngest Runner, External Email Service, Database
- Browser → Next.js (page requests, API calls)
- Next.js → Convex (RPC calls via convex-client)
- Inngest → Convex (job triggers)
- Convex → DB (read/write)
- Inngest/Convex → Email Service (send reminders)
- Orange for background workflows (Inngest jobs)
- Gray for external services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Browser["Browser"]:::external
        Browser --> NextJS["Next.js Frontend"]:::frontend
        subgraph "Next.js App Router"
            direction TB
            subgraph "Auth Routes (app/(auth))"
                direction TB
                AuthLayout["(auth) layout"]:::frontend
                SignIn["sign-in page"]:::frontend
                SignUp["sign-up page"]:::frontend
                AuthLayout --> SignIn
                AuthLayout --> SignUp
            end
            subgraph "Main Routes (app/(main))"
                direction TB
                MainLayout["(main) layout"]:::frontend
                Dashboard["dashboard page"]:::frontend
                Contacts["contacts page"]:::frontend
                ExpensesNew["new expense page"]:::frontend
                GroupsPage["group page"]:::frontend
                PersonPage["person page"]:::frontend
                SettlementsPage["settlements page"]:::frontend
                MainLayout --> Dashboard
                MainLayout --> Contacts
                MainLayout --> ExpensesNew
                MainLayout --> GroupsPage
                MainLayout --> PersonPage
                MainLayout --> SettlementsPage
            end
            GlobalLayout["root layout"]:::frontend
            NextJS --> AuthLayout
            NextJS --> MainLayout
            NextJS --> GlobalLayout
        end
    end

    %% UI Components
    subgraph "UI Components"
        direction TB
        Header["header.jsx"]:::ui
        ExpenseList["expense-list.jsx"]:::ui
        GroupBalances["group-balances.jsx"]:::ui
        GroupMembers["group-members.jsx"]:::ui
        SettlementsList["settlements-list.jsx"]:::ui
        ConvexProvider["convex-client-provider.jsx"]:::ui
    end
    NextJS --> Header
    NextJS --> ExpenseList
    NextJS --> GroupBalances
    NextJS --> GroupMembers
    NextJS --> SettlementsList
    NextJS --> ConvexProvider

    subgraph "Shared UI Library"
        direction TB
        Avatar["avatar.jsx"]:::ui
        Badge["badge.jsx"]:::ui
        Button["button.jsx"]:::ui
        Input["input.jsx"]:::ui
        Dialog["dialog.jsx"]:::ui
        Select["select.jsx"]:::ui
        Tabs["tabs.jsx"]:::ui
    end
    NextJS --> Avatar
    NextJS --> Badge
    NextJS --> Button
    NextJS --> Input
    NextJS --> Dialog
    NextJS --> Select
    NextJS --> Tabs

    %% Backend - Convex
    subgraph "Convex Backend"
        direction TB
        ConvexClient["Convex Client"]:::backend
        ConvexFuncs["Convex Functions"]:::backend
        ConvexDB["Convex Database"]:::db
        ConvexClient --> ConvexFuncs
        ConvexFuncs --> ConvexDB
    end
    NextJS --> ConvexClient

    %% Background Jobs - Inngest
    subgraph "Inngest Workflow"
        direction TB
        InngestWebhook["Inngest Webhook Endpoint"]:::background
        InngestRunner["Inngest Runner"]:::background
        JobDefs["Job Definitions"]:::background
        InngestWebhook --> InngestRunner
        InngestRunner --> JobDefs
        InngestRunner --> ConvexFuncs
    end
    NextJS --> InngestWebhook

    %% External Services
    subgraph "External Services"
        direction TB
        EmailService["Email Provider"]:::external
    end
    ConvexFuncs --> EmailService
    InngestRunner --> EmailService

    %% Click Events
    click AuthLayout "https://github.com/kavya-hjb217/xpnsone/blob/main/app/(auth)/layout.js"
    click SignIn "https://github.com/kavya-hjb217/xpnsone/blob/main/app/(auth)/sign-in/[[...sign-in]]/page.jsx"
    click SignUp "https://github.com/kavya-hjb217/xpnsone/blob/main/app/(auth)/sign-up/[[...sign-up]]/page.jsx"
    click MainLayout "https://github.com/kavya-hjb217/xpnsone/blob/main/app/(main)/layout.jsx"
    click Dashboard "https://github.com/kavya-hjb217/xpnsone/blob/main/app/(main)/dashboard/page.jsx"
    click Contacts "https://github.com/kavya-hjb217/xpnsone/blob/main/app/(main)/contacts/page.jsx"
    click ExpensesNew "https://github.com/kavya-hjb217/xpnsone/blob/main/app/(main)/expenses/new/page.jsx"
    click GroupsPage "https://github.com/kavya-hjb217/xpnsone/blob/main/app/(main)/groups/[id]/page.jsx"
    click PersonPage "https://github.com/kavya-hjb217/xpnsone/blob/main/app/(main)/person/[id]/page.jsx"
    click SettlementsPage "https://github.com/kavya-hjb217/xpnsone/blob/main/app/(main)/settlements/[type]/[id]/page.jsx"
    click GlobalLayout "https://github.com/kavya-hjb217/xpnsone/blob/main/app/layout.js"
    click Header "https://github.com/kavya-hjb217/xpnsone/blob/main/components/header.jsx"
    click ExpenseList "https://github.com/kavya-hjb217/xpnsone/blob/main/components/expense-list.jsx"
    click GroupBalances "https://github.com/kavya-hjb217/xpnsone/blob/main/components/group-balances.jsx"
    click GroupMembers "https://github.com/kavya-hjb217/xpnsone/blob/main/components/group-members.jsx"
    click SettlementsList "https://github.com/kavya-hjb217/xpnsone/blob/main/components/settlements-list.jsx"
    click ConvexProvider "https://github.com/kavya-hjb217/xpnsone/blob/main/components/convex-client-provider.jsx"
    click Avatar "https://github.com/kavya-hjb217/xpnsone/blob/main/components/ui/avatar.jsx"
    click Badge "https://github.com/kavya-hjb217/xpnsone/blob/main/components/ui/badge.jsx"
    click Button "https://github.com/kavya-hjb217/xpnsone/blob/main/components/ui/button.jsx"
    click Input "https://github.com/kavya-hjb217/xpnsone/blob/main/components/ui/input.jsx"
    click Dialog "https://github.com/kavya-hjb217/xpnsone/blob/main/components/ui/dialog.jsx"
    click Select "https://github.com/kavya-hjb217/xpnsone/blob/main/components/ui/select.jsx"
    click Tabs "https://github.com/kavya-hjb217/xpnsone/blob/main/components/ui/tabs.jsx"
    click ConvexClient "https://github.com/kavya-hjb217/xpnsone/blob/main/convex/_generated/server.js"
    click ConvexFuncs "https://github.com/kavya-hjb217/xpnsone/blob/main/convex/schema.js"
    click InngestWebhook "https://github.com/kavya-hjb217/xpnsone/blob/main/app/api/inngest/route.js"
    click JobDefs "https://github.com/kavya-hjb217/xpnsone/blob/main/lib/inngest/client.js"
    click EmailService "https://github.com/kavya-hjb217/xpnsone/blob/main/convex/email.js"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#0288d1,color:#000
    classDef ui fill:#b3e5fc,stroke:#0277bd,color:#000
    classDef backend fill:#c8e6c9,stroke:#388e3c,color:#000
    classDef db fill:#a5d6a7,stroke:#2e7d32,color:#000
    classDef background fill:#ffe0b2,stroke:#f57c00,color:#000
    classDef external fill:#eeeeee,stroke:#9e9e9e,color:#000
```
