sahinpro/hilful-fuzul-manobkollan-fund

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.