# sahinpro/hilful-fuzul-manobkollan-fund architecture

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

- Interactive diagram: https://gitdiagram.com/sahinpro/hilful-fuzul-manobkollan-fund
- Repository: https://github.com/sahinpro/hilful-fuzul-manobkollan-fund

## Overview

1. **Overall shape**
   - This is a Next.js App Router application with two major user-facing surfaces: a **public site** and an **authenticated admin console**.
   - The repo is organized around domain areas rather than generic CRUD screens, which makes the architecture center on business workflows: donations, receipts, finance transparency, and governance.

2. **Public site boundary**
   - `src/app/(site)` contains the public marketing/information pages: home, about, activities, annual report, notices, transparency, donate, and receipt lookup/verification.
   - Shared presentation for the public site lives in `src/components/home`, `src/components/donate`, `src/components/transparency`, `src/components/receipt`, and site-level shell pieces like header, footer, nav, page transitions, and theme/i18n providers.
   - This surface is read-heavy and mostly consumes public data, rendered through server components plus selective client interactivity.

3. **Donation workflow**
   - The donation flow is a dedicated subsystem spanning `src/app/(site)/donate`, `src/app/api/donate`, and `src/lib/donate`.
   - A donor creates a **donation intent** via the API, then tracks status by token; there are also receipt-related endpoints for intent receipts.
   - Core logic such as token handling, normalization, status checks, confirmation, and config is centralized in `src/lib/donate`, keeping workflow rules out of route handlers.

4. **Receipt subsystem**
   - Receipts are first-class objects in both public and admin paths.
   - Public users can verify or look up receipts via `/receipt`, `/receipt/[receiptNo]`, and `/api/receipt/*`; admin can generate HTML receipts and backfill receipt records.
   - Receipt HTML generation, number handling, donor-name search, public lookup, and asset selection are encapsulated in `src/lib/receipt`, which suggests receipt rendering is shared between API responses and page views.

5. **Admin finance console**
   - `src/app/admin/(finance)` contains the operational back office: overview, donations, donation intents, donors, expenses, executive members, advisors, and records.
   - The admin UI is built from domain-specific workspace/table/sheet components in `src/components/admin`, with shells for sidebar, chrome, KPI cards, forms, exports, and charts.
   - This area is optimized for data management and review rather than public presentation, and its layout is isolated from the public site.

6. **Admin API layer**
   - `src/app/api/admin/*` exposes the backend for finance operations: managing donation intents, donations, donors, expenses, leadership members, stats, ledger trend, exports, and receipt backfills.
   - Route handlers are thin integration points; most business logic is pushed into `src/lib/admin`, `src/lib/finance`, `src/lib/receipt`, and related validation modules.
   - This cleanly separates HTTP concerns from domain rules and makes the API the boundary between the admin UI and persistence.

7. **Persistence and backend access**
   - The app uses **Supabase** as its backend data store/access layer, with separate client/server/service helpers in `src/lib/supabase`.
   - `src/lib/supabase/public-read.ts` and `public-receipt.ts` indicate restricted read paths for public-facing data, while `service.ts` and `server.ts` support privileged server-side operations.
   - The architecture therefore distinguishes between public reads, authenticated admin access, and service-role actions for maintenance or backfills.

8. **Caching and invalidation**
   - Public data is explicitly cached and invalidated through `src/lib/cache/public-data.ts`, `invalidate-public.ts`, and `tags.ts`.
   - This suggests a performance-oriented design where admin mutations update data, then trigger cache refreshes so public pages like transparency, home stats, and reports stay consistent.
   - In architecture terms, the cache sits between the admin mutation path and public rendering.

9. **Internationalization and localization**
   - Both public and admin areas are localized, with message catalogs under `src/messages/site` and `src/messages/admin` in Bengali and English.
   - Separate i18n helpers exist for site and admin (`src/lib/i18n/*`), and the UI includes language switchers for both surfaces.
   - The language boundary matters for the diagram because many pages are presentation-only but still depend on locale-aware data formatting and translated copy.

10. **Security and session handling**
   - `src/middleware.ts` plus `src/lib/supabase/middleware.ts` imply request-time session or auth handling at the edge/middleware layer.
   - Admin access is protected by login/reset-password flows and `src/lib/admin/auth.ts`, while rate limiting in `src/lib/security/rate-limit.ts` protects sensitive endpoints.
   - This creates a clear boundary: anonymous public browsing vs authenticated/admin-only operations.

11. **Finance and transparency features**
   - `src/lib/finance` and `src/components/transparency` power dashboards, charts, ledger views, and public financial reporting.
   - Admin exports such as the finance sheet route and HTML export helpers indicate the system produces downstream reporting artifacts, not just UI views.
   - The transparency area is a public projection of curated finance data, likely derived from the same underlying donation/expense records used in admin.

12. **Governance and publishing**
   - Leadership/resolution content is modeled separately in `src/lib/site`, `src/lib/resolution`, and related components/pages.
   - There are dedicated routes for annual reports, notices, activities, resolutions, and executive/leadership views, showing the app also serves organizational governance content, not just transactions.
   - Public governance pages are likely fed from structured data plus rendered documents such as printable resolutions.

13. **Shared UI and page composition**
   - Cross-cutting UI primitives live in `src/components/ui`, while motion/transition helpers, page shells, theme bootstrapping, and general layout components are shared across both site and admin.
   - This shared layer reduces duplication and keeps visual behavior consistent, but the real architectural separation remains domain-based: site, admin, API, and shared libs.

14. **Diagram take-away**
   - The most important flows to show are: **public content rendering**, **donation intent creation and status tracking**, **admin finance mutation and review**, **receipt generation/verification**, and **public transparency reporting**.
   - The main backend boundary is **Supabase**, with Next.js route handlers and server components orchestrating access, while cache invalidation keeps public pages synced after admin changes.

Main entry points: [`src/app/(site)`](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/tree/main/src/app/(site)) (Site app), [`src/app/api/admin/donations/route.ts`](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/app/api/admin/donations/route.ts) (Admin API), [`src/lib/receipt/donation-receipt-html.ts`](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/lib/receipt/donation-receipt-html.ts) (Domain libs), [`src/lib/supabase/server.ts`](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/lib/supabase/server.ts) (Supabase layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_site["Public site"]
  node_site_app["Site app<br/>Next.js routes"]
  node_site_shell["Site shell<br/>layout/ui<br/>[site-header.tsx]"]
  node_home_content["Home content<br/>public UI"]
  node_donation_ui["Donate UI<br/>public workflow UI"]
  node_receipt_ui["Receipt UI<br/>public workflow UI"]
  node_transparency_ui["Transparency UI<br/>public reporting UI"]
  node_governance_content["Governance content<br/>public documents"]
end

subgraph group_admin_console["Admin console"]
  node_admin_app["Admin app<br/>Next.js routes"]
  node_admin_shell["Admin shell<br/>admin UI shell<br/>[admin-chrome.tsx]"]
  node_finance_workspace["Finance workspace<br/>admin UI"]
  node_leadership_workspace["Leadership workspace<br/>admin UI"]
  node_admin_auth["Admin auth<br/>session/auth<br/>[auth.ts]"]
end

subgraph group_api_surface["API surface"]
  node_donate_api["Donate API<br/>route handlers<br/>[route.ts]"]
  node_receipt_api["Receipt API<br/>route handlers<br/>[route.ts]"]
  node_admin_api["Admin API<br/>route handlers<br/>[route.ts]"]
end

subgraph group_shared_platform["Shared platform"]
  node_cache_layer["Cache layer<br/>tagged cache<br/>[public-data.ts]"]
  node_supabase_layer["Supabase layer<br/>data access<br/>[server.ts]"]
  node_domain_libs["Domain libs<br/>business logic"]
  node_i18n_ui["i18n UI<br/>localization<br/>[site-server.ts]"]
  node_security_layer["Security layer<br/>middleware/security<br/>[middleware.ts]"]
end

node_site_app -->|"renders"| node_site_shell
node_site_shell -->|"composes"| node_home_content
node_site_app -->|"hosts"| node_donation_ui
node_site_app -->|"hosts"| node_receipt_ui
node_site_app -->|"hosts"| node_transparency_ui
node_site_app -->|"hosts"| node_governance_content
node_donation_ui -->|"calls"| node_donate_api
node_receipt_ui -->|"calls"| node_receipt_api
node_transparency_ui -->|"reads"| node_cache_layer
node_finance_workspace -->|"calls"| node_admin_api
node_leadership_workspace -->|"calls"| node_admin_api
node_admin_app -->|"renders"| node_admin_shell
node_admin_shell -->|"composes"| node_finance_workspace
node_admin_shell -->|"composes"| node_leadership_workspace
node_admin_api -->|"uses"| node_domain_libs
node_donate_api -->|"uses"| node_domain_libs
node_receipt_api -->|"uses"| node_domain_libs
node_admin_api -->|"invalidates"| node_cache_layer
node_domain_libs -->|"reads/writes"| node_supabase_layer
node_admin_api -->|"reads/writes"| node_supabase_layer
node_donate_api -->|"reads/writes"| node_supabase_layer
node_receipt_api -->|"reads"| node_supabase_layer
node_site_shell -->|"uses"| node_i18n_ui
node_admin_shell -->|"uses"| node_i18n_ui
node_security_layer -->|"protects"| node_admin_auth
node_security_layer -->|"bridges"| node_supabase_layer
node_cache_layer -->|"feeds"| node_domain_libs

click node_site_app "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/tree/main/src/app/(site)"
click node_site_shell "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/components/site-header.tsx"
click node_home_content "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/tree/main/src/components/home"
click node_donation_ui "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/components/donate/donate-workspace.tsx"
click node_receipt_ui "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/components/receipt/receipt-verify-workspace.tsx"
click node_transparency_ui "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/components/transparency/transparency-charts.tsx"
click node_governance_content "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/components/about-resolution-content.tsx"
click node_admin_app "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/tree/main/src/app/admin/(finance)"
click node_admin_shell "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/components/admin/admin-chrome.tsx"
click node_finance_workspace "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/components/admin/admin-finance-overview.tsx"
click node_leadership_workspace "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/components/admin/admin-leadership-workspace.tsx"
click node_admin_auth "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/lib/admin/auth.ts"
click node_donate_api "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/app/api/donate/intent/route.ts"
click node_receipt_api "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/app/api/receipt/lookup/route.ts"
click node_admin_api "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/app/api/admin/donations/route.ts"
click node_cache_layer "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/lib/cache/public-data.ts"
click node_supabase_layer "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/lib/supabase/server.ts"
click node_domain_libs "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/lib/receipt/donation-receipt-html.ts"
click node_i18n_ui "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/lib/i18n/site-server.ts"
click node_security_layer "https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/middleware.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_site_app,node_site_shell,node_home_content,node_donation_ui,node_receipt_ui,node_transparency_ui,node_governance_content toneBlue
class node_admin_app,node_admin_shell,node_finance_workspace,node_leadership_workspace,node_admin_auth toneAmber
class node_donate_api,node_receipt_api,node_admin_api toneMint
class node_cache_layer,node_supabase_layer,node_domain_libs,node_i18n_ui,node_security_layer toneRose
```

## Components

### Public site

Anonymous browsing, donation entry, receipt lookup, and public transparency/governance pages.

- [Site app](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/tree/main/src/app/(site)): Next.js routes · Public App Router pages and layout for the marketing and self-service site. · `src/app/(site)`
- [Site shell](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/components/site-header.tsx): layout/ui · Header, footer, navigation, theme, motion, and page composition for the public surface. · `src/components/site-header.tsx`
- [Home content](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/tree/main/src/components/home): public UI · Homepage sections, hero, activities snapshot, commitments, FAQ, and stats. · `src/components/home`
- [Donate UI](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/components/donate/donate-workspace.tsx): public workflow UI · Donation entry and status workspace for creating and tracking donation intents. · `src/components/donate/donate-workspace.tsx`
- [Receipt UI](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/components/receipt/receipt-verify-workspace.tsx): public workflow UI · Receipt verification and detail views for public lookup by receipt number. · `src/components/receipt/receipt-verify-workspace.tsx`
- [Transparency UI](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/components/transparency/transparency-charts.tsx): public reporting UI · Charts, ledger views, and stats for public finance transparency. · `src/components/transparency/transparency-charts.tsx`
- [Governance content](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/components/about-resolution-content.tsx): public documents · About, activities, notices, annual report, and resolution content for organizational governance. · `src/components/about-resolution-content.tsx`

### Admin console

Authenticated finance operations, review workflows, and back-office UI.

- [Admin app](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/tree/main/src/app/admin/(finance)): Next.js routes · Authenticated finance console routes and layout under the admin area. · `src/app/admin/(finance)`
- [Admin shell](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/components/admin/admin-chrome.tsx): admin UI shell · Sidebar, chrome, header, language switcher, and page framing for the finance console. · `src/components/admin/admin-chrome.tsx`
- [Finance workspace](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/components/admin/admin-finance-overview.tsx): admin UI · Overview, KPI cards, tables, forms, exports, and charts for finance operations. · `src/components/admin/admin-finance-overview.tsx`
- [Leadership workspace](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/components/admin/admin-leadership-workspace.tsx): admin UI · Workspaces and form sheets for executive members, advisors, and related records. · `src/components/admin/admin-leadership-workspace.tsx`
- [Admin auth](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/lib/admin/auth.ts): session/auth · Admin login, reset-password, and finance gating logic for protected operations. · `src/lib/admin/auth.ts`

### API surface

Route handlers that mediate donation, receipt, resolution, and admin data operations.

- [Donate API](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/app/api/donate/intent/route.ts): route handlers · Endpoints for creating donation intents, checking status, and serving intent receipt HTML. · `src/app/api/donate/intent/route.ts`
- [Receipt API](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/app/api/receipt/lookup/route.ts): route handlers · Public receipt lookup and HTML endpoints for receipt retrieval and rendering. · `src/app/api/receipt/lookup/route.ts`
- [Admin API](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/app/api/admin/donations/route.ts): route handlers · Back-office endpoints for donations, donors, expenses, leadership, stats, exports, and backfills. · `src/app/api/admin/donations/route.ts`

### Shared platform

Cross-cutting libraries for data access, caching, localization, security, and UI primitives.

- [Cache layer](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/lib/cache/public-data.ts): tagged cache · Public data caching and invalidation used to keep public views in sync after mutations. · `src/lib/cache/public-data.ts`
- [Supabase layer](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/lib/supabase/server.ts): data access · Client, server, service, public-read, and middleware helpers for database access. · `src/lib/supabase/server.ts`
- [Domain libs](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/lib/receipt/donation-receipt-html.ts): business logic · Donation, receipt, finance, resolution, site, and validation logic shared across routes and UI. · `src/lib/receipt/donation-receipt-html.ts`
- [i18n UI](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/lib/i18n/site-server.ts): localization · Site/admin locale helpers, message catalogs, and language switchers for both surfaces. · `src/lib/i18n/site-server.ts`
- [Security layer](https://github.com/sahinpro/hilful-fuzul-manobkollan-fund/blob/main/src/middleware.ts): middleware/security · Request-time middleware, rate limiting, and Supabase session handling at the edge. · `src/middleware.ts`

## Connections

- Site app → Site shell: renders · Public pages use the shared site frame and navigation.
- Site shell → Home content: composes · The public shell frames the home and content sections.
- Site app → Donate UI: hosts · Donation pages mount the donate workspace and status flow.
- Site app → Receipt UI: hosts · Receipt pages mount verification and lookup views.
- Site app → Transparency UI: hosts · Public transparency pages render reporting components.
- Site app → Governance content: hosts · About, annual report, notices, and resolution pages use governance content.
- Donate UI → Donate API: calls · Donation forms create and track intents through the API.
- Receipt UI → Receipt API: calls · Public receipt views query lookup and HTML endpoints.
- Transparency UI → Cache layer: reads · Public finance reporting consumes cached public data.
- Finance workspace → Admin API: calls · Admin tables, forms, exports, and dashboards mutate and fetch through admin endpoints.
- Leadership workspace → Admin API: calls · Leadership and records management use the admin API boundary.
- Admin app → Admin shell: renders · Admin routes are framed by the sidebar and console chrome.
- Admin shell → Finance workspace: composes · The finance shell presents KPIs, tables, sheets, and charts.
- Admin shell → Leadership workspace: composes · Leadership and records management live inside the admin shell.
- Admin API → Domain libs: uses · Admin handlers rely on shared domain logic for finance and receipt workflows.
- Donate API → Domain libs: uses · Donation intent handling depends on donation and receipt rules.
- Receipt API → Domain libs: uses · Receipt lookup and HTML generation use shared receipt logic.
- Admin API → Cache layer: invalidates · Admin mutations refresh public caches after changes.
- Domain libs → Supabase layer: reads/writes · Business logic and helpers persist to Supabase through server/service clients.
- Admin API → Supabase layer: reads/writes · Admin endpoints perform privileged database operations through Supabase.
- Donate API → Supabase layer: reads/writes · Donation intent routes store and query backend records.
- Receipt API → Supabase layer: reads · Receipt lookup reads public receipt data from Supabase.
- Site shell → i18n UI: uses · Public navigation and page chrome are locale-aware.
- Admin shell → i18n UI: uses · Admin chrome and forms are localized.
- Security layer → Admin auth: protects · Middleware and rate limiting support protected admin access.
- Security layer → Supabase layer: bridges · Middleware integrates Supabase session handling for requests.
- Cache layer → Domain libs: feeds · Cached public projections are derived from shared finance and receipt data.