# riteshkrkarn/evenly architecture

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

- Interactive diagram: https://gitdiagram.com/riteshkrkarn/evenly
- Repository: https://github.com/riteshkrkarn/evenly

## Overview

Evenly is a private shared-expense ledger: people create groups or friend connections, record and split expenses, review balances, and record transfers (without moving money). The graph also preserves the documented activity, notification, analytics, export, and reminder capabilities. Sampled source confirms authentication, database access, reminder and export routes, and several client-to-action links; unsampled action internals are represented only at their existing paths, with uncertain wiring omitted.

Main entry points: [`src/db/index.ts`](https://github.com/riteshkrkarn/evenly/blob/main/src/db/index.ts) (Application database), [`src/lib/group-data.ts`](https://github.com/riteshkrkarn/evenly/blob/main/src/lib/group-data.ts) (Group data and access), [`src/app/api/cron/monthly-reminders/route.ts`](https://github.com/riteshkrkarn/evenly/blob/main/src/app/api/cron/monthly-reminders/route.ts) (Monthly reminders), [`src/actions/auth.ts`](https://github.com/riteshkrkarn/evenly/blob/main/src/actions/auth.ts) (Account actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity"]
  node_auth_ui["Login and register<br/>[page.tsx]"]
  node_auth_actions["Account actions<br/>[auth.ts]"]
  node_auth_service["Credentials and sessions<br/>[auth.ts]"]
end

subgraph group_ledger["Shared ledger"]
  node_group_ui["Group and expense screens<br/>[expense-forms.tsx]"]
  node_group_actions["Group actions<br/>[groups.ts]"]
  node_expense_actions["Expense actions<br/>[expenses.ts]"]
  node_friends_ui["Friends screen<br/>[friends-client.tsx]"]
  node_friends_actions["Friend actions<br/>[friends.ts]"]
  node_settle_ui["Settlement screen<br/>[settle-client.tsx]"]
  node_settle_actions["Settlement actions<br/>[settlements.ts]"]
  node_balance_logic["Balance calculations<br/>[balances.ts]"]
  node_group_data["Group data and access<br/>[group-data.ts]"]
end

subgraph group_insights["Insights and sync"]
  node_analytics_ui["Analytics screens<br/>[page.tsx]"]
  node_activity_ui["Activity and transfers<br/>[page.tsx]"]
  node_notification_actions["Notification actions<br/>[notifications.ts]"]
  node_advanced_actions["Export and advanced actions<br/>[advanced.ts]"]
  node_export_route["Group data export<br/>[route.ts]"]
  node_reminders_route["Monthly reminders<br/>[route.ts]"]
end

subgraph group_runtime["Application runtime"]
  node_app_ui["Signed-in screens<br/>[layout.tsx]"]
  node_profile_actions["Profile actions<br/>[profile.ts]"]
  node_db[("Application database<br/>[index.ts]")]
  node_schema["Ledger data model<br/>[schema.ts]"]
end

node_person(("Person"))
node_email["Email service"]

node_person -->|"signs up or in"| node_auth_ui
node_auth_ui -->|"submits credentials"| node_auth_actions
node_auth_actions -->|"signs in"| node_auth_service
node_auth_actions -->|"reads and writes accounts"| node_db
node_auth_service -->|"checks credentials"| node_db
node_person -->|"uses app"| node_app_ui
node_app_ui -->|"opens ledger screens"| node_group_ui
node_group_ui -->|"manages groups"| node_group_actions
node_group_ui -->|"records expenses"| node_expense_actions
node_group_actions -->|"reads and writes groups"| node_db
node_expense_actions -->|"reads and writes expenses"| node_db
node_expense_actions -->|"uses group data"| node_group_data
node_friends_ui -->|"sends friend request"| node_friends_actions
node_friends_actions -->|"reads and writes friendships"| node_db
node_settle_ui -->|"records transfer"| node_settle_actions
node_settle_actions -->|"writes settlements"| node_db
node_group_data -->|"reads group records"| node_db
node_group_data -->|"computes balances"| node_balance_logic
node_analytics_ui -->|"loads group summaries"| node_group_data
node_activity_ui -.->|"presents activity"| node_app_ui
node_person -.->|"manages notifications"| node_notification_actions
node_export_route -->|"requests export data"| node_advanced_actions
node_advanced_actions -->|"reads export records"| node_db
node_reminders_route -->|"reads users and groups"| node_db
node_reminders_route -->|"loads balances and members"| node_group_data
node_reminders_route -->|"sends due digest"| node_email
node_person -->|"updates profile"| node_profile_actions
node_profile_actions -->|"writes profile"| node_db
node_db -->|"uses data model"| node_schema

click node_auth_ui "https://github.com/riteshkrkarn/evenly/blob/main/src/app/(auth)/login/page.tsx"
click node_auth_actions "https://github.com/riteshkrkarn/evenly/blob/main/src/actions/auth.ts"
click node_auth_service "https://github.com/riteshkrkarn/evenly/blob/main/src/auth.ts"
click node_app_ui "https://github.com/riteshkrkarn/evenly/blob/main/src/app/(app)/layout.tsx"
click node_group_ui "https://github.com/riteshkrkarn/evenly/blob/main/src/app/(app)/groups/%5Bid%5D/expenses/%5BexpenseId%5D/expense-forms.tsx"
click node_group_actions "https://github.com/riteshkrkarn/evenly/blob/main/src/actions/groups.ts"
click node_expense_actions "https://github.com/riteshkrkarn/evenly/blob/main/src/actions/expenses.ts"
click node_friends_ui "https://github.com/riteshkrkarn/evenly/blob/main/src/app/(app)/friends/friends-client.tsx"
click node_friends_actions "https://github.com/riteshkrkarn/evenly/blob/main/src/actions/friends.ts"
click node_settle_ui "https://github.com/riteshkrkarn/evenly/blob/main/src/app/(app)/groups/%5Bid%5D/settle/settle-client.tsx"
click node_settle_actions "https://github.com/riteshkrkarn/evenly/blob/main/src/actions/settlements.ts"
click node_balance_logic "https://github.com/riteshkrkarn/evenly/blob/main/src/lib/balances.ts"
click node_group_data "https://github.com/riteshkrkarn/evenly/blob/main/src/lib/group-data.ts"
click node_analytics_ui "https://github.com/riteshkrkarn/evenly/blob/main/src/app/(app)/analytics/page.tsx"
click node_activity_ui "https://github.com/riteshkrkarn/evenly/blob/main/src/app/(app)/activity/page.tsx"
click node_notification_actions "https://github.com/riteshkrkarn/evenly/blob/main/src/actions/notifications.ts"
click node_advanced_actions "https://github.com/riteshkrkarn/evenly/blob/main/src/actions/advanced.ts"
click node_export_route "https://github.com/riteshkrkarn/evenly/blob/main/src/app/(app)/groups/%5Bid%5D/export/route.ts"
click node_reminders_route "https://github.com/riteshkrkarn/evenly/blob/main/src/app/api/cron/monthly-reminders/route.ts"
click node_profile_actions "https://github.com/riteshkrkarn/evenly/blob/main/src/actions/profile.ts"
click node_db "https://github.com/riteshkrkarn/evenly/blob/main/src/db/index.ts"
click node_schema "https://github.com/riteshkrkarn/evenly/blob/main/src/db/schema.ts"

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_ui,node_auth_actions,node_auth_service toneBlue
class node_group_ui,node_group_actions,node_expense_actions,node_friends_ui,node_friends_actions,node_settle_ui,node_settle_actions,node_balance_logic,node_group_data toneAmber
class node_analytics_ui,node_activity_ui,node_notification_actions,node_advanced_actions,node_export_route,node_reminders_route toneMint
class node_app_ui,node_profile_actions,node_db,node_schema toneRose
class node_person,node_email toneIndigo
```

## Components

### Identity

- [Login and register](https://github.com/riteshkrkarn/evenly/blob/main/src/app/(auth)/login/page.tsx): `src/app/(auth)/login/page.tsx`
- [Account actions](https://github.com/riteshkrkarn/evenly/blob/main/src/actions/auth.ts): `src/actions/auth.ts`
- [Credentials and sessions](https://github.com/riteshkrkarn/evenly/blob/main/src/auth.ts): `src/auth.ts`

### Shared ledger

- [Group and expense screens](https://github.com/riteshkrkarn/evenly/blob/main/src/app/(app)/groups/%5Bid%5D/expenses/%5BexpenseId%5D/expense-forms.tsx): `src/app/(app)/groups/[id]/expenses/[expenseId]/expense-forms.tsx`
- [Group actions](https://github.com/riteshkrkarn/evenly/blob/main/src/actions/groups.ts): `src/actions/groups.ts`
- [Expense actions](https://github.com/riteshkrkarn/evenly/blob/main/src/actions/expenses.ts): `src/actions/expenses.ts`
- [Friends screen](https://github.com/riteshkrkarn/evenly/blob/main/src/app/(app)/friends/friends-client.tsx): `src/app/(app)/friends/friends-client.tsx`
- [Friend actions](https://github.com/riteshkrkarn/evenly/blob/main/src/actions/friends.ts): `src/actions/friends.ts`
- [Settlement screen](https://github.com/riteshkrkarn/evenly/blob/main/src/app/(app)/groups/%5Bid%5D/settle/settle-client.tsx): `src/app/(app)/groups/[id]/settle/settle-client.tsx`
- [Settlement actions](https://github.com/riteshkrkarn/evenly/blob/main/src/actions/settlements.ts): `src/actions/settlements.ts`
- [Balance calculations](https://github.com/riteshkrkarn/evenly/blob/main/src/lib/balances.ts): `src/lib/balances.ts`
- [Group data and access](https://github.com/riteshkrkarn/evenly/blob/main/src/lib/group-data.ts): `src/lib/group-data.ts`

### Insights and sync

- [Analytics screens](https://github.com/riteshkrkarn/evenly/blob/main/src/app/(app)/analytics/page.tsx): `src/app/(app)/analytics/page.tsx`
- [Activity and transfers](https://github.com/riteshkrkarn/evenly/blob/main/src/app/(app)/activity/page.tsx): `src/app/(app)/activity/page.tsx`
- [Notification actions](https://github.com/riteshkrkarn/evenly/blob/main/src/actions/notifications.ts): `src/actions/notifications.ts`
- [Export and advanced actions](https://github.com/riteshkrkarn/evenly/blob/main/src/actions/advanced.ts): `src/actions/advanced.ts`
- [Group data export](https://github.com/riteshkrkarn/evenly/blob/main/src/app/(app)/groups/%5Bid%5D/export/route.ts): `src/app/(app)/groups/[id]/export/route.ts`
- [Monthly reminders](https://github.com/riteshkrkarn/evenly/blob/main/src/app/api/cron/monthly-reminders/route.ts): `src/app/api/cron/monthly-reminders/route.ts`

### Application runtime

- [Signed-in screens](https://github.com/riteshkrkarn/evenly/blob/main/src/app/(app)/layout.tsx): `src/app/(app)/layout.tsx`
- [Profile actions](https://github.com/riteshkrkarn/evenly/blob/main/src/actions/profile.ts): `src/actions/profile.ts`
- [Application database](https://github.com/riteshkrkarn/evenly/blob/main/src/db/index.ts): `src/db/index.ts`
- [Ledger data model](https://github.com/riteshkrkarn/evenly/blob/main/src/db/schema.ts): `src/db/schema.ts`

### Other components

- **Person**
- **Email service**

## Connections

- Person → Login and register: signs up or in
- Login and register → Account actions: submits credentials
- Account actions → Credentials and sessions: signs in
- Account actions → Application database: reads and writes accounts
- Credentials and sessions → Application database: checks credentials
- Person → Signed-in screens: uses app
- Signed-in screens → Group and expense screens: opens ledger screens
- Group and expense screens → Group actions: manages groups
- Group and expense screens → Expense actions: records expenses
- Group actions → Application database: reads and writes groups
- Expense actions → Application database: reads and writes expenses
- Expense actions → Group data and access: uses group data
- Friends screen → Friend actions: sends friend request
- Friend actions → Application database: reads and writes friendships
- Settlement screen → Settlement actions: records transfer
- Settlement actions → Application database: writes settlements
- Group data and access → Application database: reads group records
- Group data and access → Balance calculations: computes balances
- Analytics screens → Group data and access: loads group summaries
- Activity and transfers → Signed-in screens: presents activity
- Person → Notification actions: manages notifications
- Group data export → Export and advanced actions: requests export data
- Export and advanced actions → Application database: reads export records
- Monthly reminders → Application database: reads users and groups
- Monthly reminders → Group data and access: loads balances and members
- Monthly reminders → Email service: sends due digest
- Person → Profile actions: updates profile
- Profile actions → Application database: writes profile
- Application database → Ledger data model: uses data model