# mallikarjun1520/impactledger architecture

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

- Interactive diagram: https://gitdiagram.com/mallikarjun1520/impactledger
- Repository: https://github.com/mallikarjun1520/impactledger

## Overview

ImpactLedger is an early-stage provenance API for organizations to record contributions, resource inventory, and relief distributions. The intended user workflow is to authenticate, act within an organization, record lifecycle events, and query resulting records; sampled code confirms organization membership and distribution/inventory behavior. The web page remains a Next.js starter, and README-listed passkeys, storage, blockchain anchoring, and LLM interaction are not evidenced as implemented here, so their runtime links are omitted.

Main entry points: [`apps/api/app/main.py`](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/main.py) (FastAPI app), [`apps/api/app/api/v1/organizations.py`](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/api/v1/organizations.py) (Organization routes), [`apps/api/app/core/authorization.py`](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/core/authorization.py) (Membership checks), [`apps/api/app/core/auth.py`](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/core/auth.py) (JWT verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API entry"]
  node_api["FastAPI app<br/>[main.py]"]
  node_web["Starter web page<br/>[page.tsx]"]
  node_health_routes["Health route<br/>[health.py]"]
end

subgraph group_identity["Identity and tenancy"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_auth_core["JWT verification<br/>[auth.py]"]
  node_authorization["Membership checks<br/>[authorization.py]"]
  node_supabase_auth["Supabase Auth"]
  node_org_routes["Organization routes<br/>[organizations.py]"]
end

subgraph group_records["Lifecycle records"]
  node_contrib_routes["Contribution routes<br/>[contributions.py]"]
  node_allocation_routes["Allocation routes<br/>[allocations.py]"]
  node_resource_routes["Resource routes<br/>[resources.py]"]
  node_distribution_routes["Distribution routes<br/>[distributions.py]"]
end

subgraph group_persistence["Persistence"]
  node_members_db["Membership data access"]
  node_org_db["Organization data access<br/>[organizations.py]"]
  node_resource_db["Resource ledger access<br/>[resources.py]"]
  node_distribution_db["Distribution and inventory<br/>[distributions.py]"]
  node_postgres[("Supabase PostgreSQL")]
end

node_user(("API user"))

node_user -->|"sends requests"| node_api
node_api -->|"registers"| node_auth_routes
node_api -->|"registers"| node_org_routes
node_api -->|"registers"| node_distribution_routes
node_api -->|"registers"| node_health_routes
node_auth_routes -->|"validates identity"| node_auth_core
node_auth_core -->|"fetches signing keys"| node_supabase_auth
node_auth_routes -->|"checks membership"| node_authorization
node_authorization -->|"resolves user"| node_auth_core
node_authorization -->|"looks up membership"| node_members_db
node_org_routes -->|"authenticates requests"| node_auth_core
node_org_routes -->|"checks membership"| node_authorization
node_org_routes -->|"manages members"| node_members_db
node_org_routes -->|"reads and creates organizations"| node_org_db
node_members_db -->|"reads and writes"| node_postgres
node_org_db -->|"reads and writes"| node_postgres
node_resource_db -->|"reads and writes"| node_postgres
node_distribution_db -->|"reads and writes"| node_postgres
node_distribution_db -->|"records inventory event"| node_resource_db
node_web -.->|"displays starter page"| node_user

click node_api "https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/main.py"
click node_web "https://github.com/mallikarjun1520/impactledger/blob/main/apps/web/src/app/page.tsx"
click node_auth_routes "https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/api/v1/auth.py"
click node_auth_core "https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/core/auth.py"
click node_authorization "https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/core/authorization.py"
click node_org_routes "https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/api/v1/organizations.py"
click node_members_db "https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/infrastructure/database/organization_members.py"
click node_org_db "https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/infrastructure/database/organizations.py"
click node_contrib_routes "https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/api/v1/contributions.py"
click node_allocation_routes "https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/api/v1/allocations.py"
click node_resource_routes "https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/api/v1/resources.py"
click node_resource_db "https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/infrastructure/database/resources.py"
click node_distribution_routes "https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/api/v1/distributions.py"
click node_distribution_db "https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/infrastructure/database/distributions.py"
click node_postgres "https://github.com/mallikarjun1520/impactledger/blob/main/supabase/migrations/001_create_organizations.sql"
click node_health_routes "https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/api/v1/health.py"

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_api,node_web,node_health_routes,node_user toneBlue
class node_auth_routes,node_auth_core,node_authorization,node_supabase_auth,node_org_routes toneAmber
class node_contrib_routes,node_allocation_routes,node_resource_routes,node_distribution_routes toneMint
class node_members_db,node_org_db,node_resource_db,node_distribution_db,node_postgres toneRose
```

## Components

### API entry

- [FastAPI app](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [Starter web page](https://github.com/mallikarjun1520/impactledger/blob/main/apps/web/src/app/page.tsx): `apps/web/src/app/page.tsx`
- [Health route](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/api/v1/health.py): `apps/api/app/api/v1/health.py`

### Identity and tenancy

- [Auth routes](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/api/v1/auth.py): `apps/api/app/api/v1/auth.py`
- [JWT verification](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/core/auth.py): `apps/api/app/core/auth.py`
- [Membership checks](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/core/authorization.py): `apps/api/app/core/authorization.py`
- **Supabase Auth**
- [Organization routes](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/api/v1/organizations.py): `apps/api/app/api/v1/organizations.py`

### Lifecycle records

- [Contribution routes](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/api/v1/contributions.py): `apps/api/app/api/v1/contributions.py`
- [Allocation routes](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/api/v1/allocations.py): `apps/api/app/api/v1/allocations.py`
- [Resource routes](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/api/v1/resources.py): `apps/api/app/api/v1/resources.py`
- [Distribution routes](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/api/v1/distributions.py): `apps/api/app/api/v1/distributions.py`

### Persistence

- [Membership data access](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/infrastructure/database/organization_members.py): `apps/api/app/infrastructure/database/organization_members.py`
- [Organization data access](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/infrastructure/database/organizations.py): `apps/api/app/infrastructure/database/organizations.py`
- [Resource ledger access](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/infrastructure/database/resources.py): `apps/api/app/infrastructure/database/resources.py`
- [Distribution and inventory](https://github.com/mallikarjun1520/impactledger/blob/main/apps/api/app/infrastructure/database/distributions.py): `apps/api/app/infrastructure/database/distributions.py`
- [Supabase PostgreSQL](https://github.com/mallikarjun1520/impactledger/blob/main/supabase/migrations/001_create_organizations.sql): `supabase/migrations/001_create_organizations.sql`

### Other components

- **API user**

## Connections

- API user → FastAPI app: sends requests
- FastAPI app → Auth routes: registers
- FastAPI app → Organization routes: registers
- FastAPI app → Distribution routes: registers
- FastAPI app → Health route: registers
- Auth routes → JWT verification: validates identity
- JWT verification → Supabase Auth: fetches signing keys
- Auth routes → Membership checks: checks membership
- Membership checks → JWT verification: resolves user
- Membership checks → Membership data access: looks up membership
- Organization routes → JWT verification: authenticates requests
- Organization routes → Membership checks: checks membership
- Organization routes → Membership data access: manages members
- Organization routes → Organization data access: reads and creates organizations
- Membership data access → Supabase PostgreSQL: reads and writes
- Organization data access → Supabase PostgreSQL: reads and writes
- Resource ledger access → Supabase PostgreSQL: reads and writes
- Distribution and inventory → Supabase PostgreSQL: reads and writes
- Distribution and inventory → Resource ledger access: records inventory event
- Starter web page → API user: displays starter page