# nox-mob/openledger architecture

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

- Interactive diagram: https://gitdiagram.com/nox-mob/openledger
- Repository: https://github.com/nox-mob/openledger

## Overview

Open Ledger is a self-hostable double-entry accounting app for small businesses and nonprofits. Users sign in, choose or create an organization, then manage its ledger: import bank statements as reviewable evidence, post transactions, reconcile accounts, and review reports. Organization settings cover accounts, members, terminology, and period close. Supabase provides authentication and organization-scoped data; the README describes row-level security and a database trigger enforcing balanced posted entries. Several feature routes and functions are represented by their exact tree paths because their implementations were not sampled.

Main entry points: [`src/lib/org.functions.ts`](https://github.com/nox-mob/openledger/blob/main/src/lib/org.functions.ts) (Organization functions), [`src/lib/import.functions.ts`](https://github.com/nox-mob/openledger/blob/main/src/lib/import.functions.ts) (Import operations), [`src/routes/_authenticated/route.tsx`](https://github.com/nox-mob/openledger/blob/main/src/routes/_authenticated/route.tsx) (Authenticated gate), [`src/lib/reports.functions.ts`](https://github.com/nox-mob/openledger/blob/main/src/lib/reports.functions.ts) (Reports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Access and shell"]
  node_authpage["Sign in<br/>[auth.tsx]"]
  node_authroute["Authenticated gate<br/>[route.tsx]"]
  node_shell["App shell<br/>[AppShell.tsx]"]
  node_legal["Legal acceptance<br/>[LegalGate.tsx]"]
end

subgraph group_org["Organization setup"]
  node_orgfunctions["Organization functions<br/>[org.functions.ts]"]
  node_onboarding["Organization onboarding<br/>[onboarding.tsx]"]
  node_settings["Organization settings"]
  node_accountsetup["Account setup<br/>[accounts.tsx]"]
end

subgraph group_ledger["Ledger operations"]
  node_importui["Bank import review<br/>[import.tsx]"]
  node_parsers["Statement parsers"]
  node_importfunctions["Import operations"]
  node_transactions["Transactions"]
  node_accounts["Accounts and funds<br/>[accounts.tsx]"]
  node_reconcile["Reconciliation"]
  node_close["Period close<br/>[close.functions.ts]"]
end

subgraph group_insight["Review and reporting"]
  node_dashboard["Dashboard<br/>[index.tsx]"]
  node_reports["Reports"]
  node_reportpdf["PDF reports<br/>[report-pdf.ts]"]
end

subgraph group_platform["Data and policy"]
  node_authmiddleware["Request authentication<br/>[auth-middleware.ts]"]
  node_browserclient["Browser Supabase client<br/>[client.ts]"]
  node_serverclient["Admin Supabase client<br/>[client.server.ts]"]
  node_permissions["Permission checks<br/>[permissions.ts]"]
  node_audit["Audit trail<br/>[audit.ts]"]
  node_database[("Supabase database")]
end

node_user(("User"))
node_authservice["Supabase Auth"]

node_user -->|"signs in"| node_authpage
node_authpage -->|"authenticates with"| node_browserclient
node_authroute -->|"checks user"| node_browserclient
node_authroute -->|"gates pages"| node_legal
node_authroute -.->|"renders routes"| node_shell
node_shell -->|"loads organizations"| node_orgfunctions
node_onboarding -.->|"configures organization"| node_orgfunctions
node_settings -.->|"manages settings"| node_orgfunctions
node_accountsetup -.->|"loads organization data"| node_orgfunctions
node_importui -->|"submits import actions"| node_importfunctions
node_importui -->|"parses and checks rows"| node_parsers
node_importfunctions -->|"requires auth"| node_authmiddleware
node_orgfunctions -->|"requires auth"| node_authmiddleware
node_importfunctions -->|"checks write access"| node_permissions
node_orgfunctions -->|"checks role access"| node_permissions
node_importfunctions -->|"records changes"| node_audit
node_orgfunctions -->|"records changes"| node_audit
node_authmiddleware -->|"validates claims"| node_database
node_browserclient -->|"manages sessions"| node_authservice
node_importfunctions -->|"reads and writes imports"| node_database
node_transactions -.->|"reads and writes ledger"| node_database
node_reconcile -.->|"reads and updates matches"| node_database
node_close -.->|"closes periods"| node_database
node_orgfunctions -.->|"reads and writes organization"| node_database
node_dashboard -->|"loads report data"| node_reports
node_reports -.->|"reads accounting data"| node_database
node_reportpdf -.->|"formats report output"| node_reports
node_serverclient -->|"admin access"| node_database

click node_authpage "https://github.com/nox-mob/openledger/blob/main/src/routes/auth.tsx"
click node_authroute "https://github.com/nox-mob/openledger/blob/main/src/routes/_authenticated/route.tsx"
click node_shell "https://github.com/nox-mob/openledger/blob/main/src/components/AppShell.tsx"
click node_legal "https://github.com/nox-mob/openledger/blob/main/src/components/LegalGate.tsx"
click node_orgfunctions "https://github.com/nox-mob/openledger/blob/main/src/lib/org.functions.ts"
click node_onboarding "https://github.com/nox-mob/openledger/blob/main/src/routes/_authenticated/onboarding.tsx"
click node_settings "https://github.com/nox-mob/openledger/tree/main/src/routes/_authenticated/settings"
click node_accountsetup "https://github.com/nox-mob/openledger/blob/main/src/routes/_authenticated/settings/accounts.tsx"
click node_importui "https://github.com/nox-mob/openledger/blob/main/src/routes/_authenticated/import.tsx"
click node_parsers "https://github.com/nox-mob/openledger/tree/main/src/lib/parsers"
click node_importfunctions "https://github.com/nox-mob/openledger/blob/main/src/lib/import.functions.ts"
click node_transactions "https://github.com/nox-mob/openledger/blob/main/src/lib/transactions.functions.ts"
click node_accounts "https://github.com/nox-mob/openledger/blob/main/src/routes/_authenticated/accounts.tsx"
click node_reconcile "https://github.com/nox-mob/openledger/blob/main/src/lib/reconcile.functions.ts"
click node_close "https://github.com/nox-mob/openledger/blob/main/src/lib/close.functions.ts"
click node_dashboard "https://github.com/nox-mob/openledger/blob/main/src/routes/_authenticated/index.tsx"
click node_reports "https://github.com/nox-mob/openledger/blob/main/src/lib/reports.functions.ts"
click node_reportpdf "https://github.com/nox-mob/openledger/blob/main/src/lib/report-pdf.ts"
click node_authmiddleware "https://github.com/nox-mob/openledger/blob/main/src/integrations/supabase/auth-middleware.ts"
click node_browserclient "https://github.com/nox-mob/openledger/blob/main/src/integrations/supabase/client.ts"
click node_serverclient "https://github.com/nox-mob/openledger/blob/main/src/integrations/supabase/client.server.ts"
click node_permissions "https://github.com/nox-mob/openledger/blob/main/src/lib/permissions.ts"
click node_audit "https://github.com/nox-mob/openledger/blob/main/src/lib/audit.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_authpage,node_authroute,node_shell,node_legal,node_user toneBlue
class node_orgfunctions,node_onboarding,node_settings,node_accountsetup toneAmber
class node_importui,node_parsers,node_importfunctions,node_transactions,node_accounts,node_reconcile,node_close toneMint
class node_dashboard,node_reports,node_reportpdf toneRose
class node_authmiddleware,node_browserclient,node_serverclient,node_permissions,node_audit,node_database,node_authservice toneIndigo
```

## Components

### Access and shell

- [Sign in](https://github.com/nox-mob/openledger/blob/main/src/routes/auth.tsx): `src/routes/auth.tsx`
- [Authenticated gate](https://github.com/nox-mob/openledger/blob/main/src/routes/_authenticated/route.tsx): `src/routes/_authenticated/route.tsx`
- [App shell](https://github.com/nox-mob/openledger/blob/main/src/components/AppShell.tsx): `src/components/AppShell.tsx`
- [Legal acceptance](https://github.com/nox-mob/openledger/blob/main/src/components/LegalGate.tsx): `src/components/LegalGate.tsx`

### Organization setup

- [Organization functions](https://github.com/nox-mob/openledger/blob/main/src/lib/org.functions.ts): `src/lib/org.functions.ts`
- [Organization onboarding](https://github.com/nox-mob/openledger/blob/main/src/routes/_authenticated/onboarding.tsx): `src/routes/_authenticated/onboarding.tsx`
- [Organization settings](https://github.com/nox-mob/openledger/tree/main/src/routes/_authenticated/settings): `src/routes/_authenticated/settings`
- [Account setup](https://github.com/nox-mob/openledger/blob/main/src/routes/_authenticated/settings/accounts.tsx): `src/routes/_authenticated/settings/accounts.tsx`

### Ledger operations

- [Bank import review](https://github.com/nox-mob/openledger/blob/main/src/routes/_authenticated/import.tsx): `src/routes/_authenticated/import.tsx`
- [Statement parsers](https://github.com/nox-mob/openledger/tree/main/src/lib/parsers): `src/lib/parsers`
- [Import operations](https://github.com/nox-mob/openledger/blob/main/src/lib/import.functions.ts): `src/lib/import.functions.ts`
- [Transactions](https://github.com/nox-mob/openledger/blob/main/src/lib/transactions.functions.ts): `src/lib/transactions.functions.ts`
- [Accounts and funds](https://github.com/nox-mob/openledger/blob/main/src/routes/_authenticated/accounts.tsx): `src/routes/_authenticated/accounts.tsx`
- [Reconciliation](https://github.com/nox-mob/openledger/blob/main/src/lib/reconcile.functions.ts): `src/lib/reconcile.functions.ts`
- [Period close](https://github.com/nox-mob/openledger/blob/main/src/lib/close.functions.ts): `src/lib/close.functions.ts`

### Review and reporting

- [Dashboard](https://github.com/nox-mob/openledger/blob/main/src/routes/_authenticated/index.tsx): `src/routes/_authenticated/index.tsx`
- [Reports](https://github.com/nox-mob/openledger/blob/main/src/lib/reports.functions.ts): `src/lib/reports.functions.ts`
- [PDF reports](https://github.com/nox-mob/openledger/blob/main/src/lib/report-pdf.ts): `src/lib/report-pdf.ts`

### Data and policy

- [Request authentication](https://github.com/nox-mob/openledger/blob/main/src/integrations/supabase/auth-middleware.ts): `src/integrations/supabase/auth-middleware.ts`
- [Browser Supabase client](https://github.com/nox-mob/openledger/blob/main/src/integrations/supabase/client.ts): `src/integrations/supabase/client.ts`
- [Admin Supabase client](https://github.com/nox-mob/openledger/blob/main/src/integrations/supabase/client.server.ts): `src/integrations/supabase/client.server.ts`
- [Permission checks](https://github.com/nox-mob/openledger/blob/main/src/lib/permissions.ts): `src/lib/permissions.ts`
- [Audit trail](https://github.com/nox-mob/openledger/blob/main/src/lib/audit.ts): `src/lib/audit.ts`
- **Supabase database**

### Other components

- **User**
- **Supabase Auth**

## Connections

- User → Sign in: signs in (evidence: `src/routes/auth.tsx`)
- Sign in → Browser Supabase client: authenticates with (evidence: `src/routes/auth.tsx`)
- Authenticated gate → Browser Supabase client: checks user (evidence: `src/routes/_authenticated/route.tsx`)
- Authenticated gate → Legal acceptance: gates pages (evidence: `src/routes/_authenticated/route.tsx`)
- Authenticated gate → App shell: renders routes
- App shell → Organization functions: loads organizations (evidence: `src/components/AppShell.tsx`)
- Organization onboarding → Organization functions: configures organization
- Organization settings → Organization functions: manages settings (evidence: `src/routes/_authenticated/settings/index.tsx`)
- Account setup → Organization functions: loads organization data
- Bank import review → Import operations: submits import actions (evidence: `src/routes/_authenticated/import.tsx`)
- Bank import review → Statement parsers: parses and checks rows (evidence: `src/routes/_authenticated/import.tsx`)
- Import operations → Request authentication: requires auth (evidence: `src/lib/import.functions.ts`)
- Organization functions → Request authentication: requires auth (evidence: `src/lib/org.functions.ts`)
- Import operations → Permission checks: checks write access (evidence: `src/lib/import.functions.ts`)
- Organization functions → Permission checks: checks role access (evidence: `src/lib/org.functions.ts`)
- Import operations → Audit trail: records changes (evidence: `src/lib/import.functions.ts`)
- Organization functions → Audit trail: records changes (evidence: `src/lib/org.functions.ts`)
- Request authentication → Supabase database: validates claims (evidence: `src/integrations/supabase/auth-middleware.ts`)
- Browser Supabase client → Supabase Auth: manages sessions (evidence: `src/integrations/supabase/client.ts`)
- Import operations → Supabase database: reads and writes imports (evidence: `src/lib/import.functions.ts`)
- Transactions → Supabase database: reads and writes ledger
- Reconciliation → Supabase database: reads and updates matches
- Period close → Supabase database: closes periods
- Organization functions → Supabase database: reads and writes organization
- Dashboard → Reports: loads report data (evidence: `src/routes/_authenticated/index.tsx`)
- Reports → Supabase database: reads accounting data
- PDF reports → Reports: formats report output
- Admin Supabase client → Supabase database: admin access (evidence: `src/integrations/supabase/client.server.ts`)
