# dncmaduro/dntt architecture

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

- Interactive diagram: https://gitdiagram.com/dncmaduro/dntt
- Repository: https://github.com/dncmaduro/dntt

## Overview

#### Purpose and Runtime
This is a Next.js App Router application for internal payment-request management: employees submit requests and expense evidence, reviewers process them, and users can view payment QR information, notifications, and profiles. It runs as a TypeScript React application, with server-rendered routes, Route Handlers, and Server Actions.

Core entry and application boundaries:
- `app/layout.tsx`
- `app/(protected)/layout.tsx`
- `proxy.ts`

#### Routing, Access Control, and Shell
The route tree separates unauthenticated authentication screens from authenticated operational screens. The protected layout is the principal authorization/UI boundary and likely hosts the shared application shell; `proxy.ts` is the request-level middleware boundary for session refresh or route protection.

Primary route groups:
- `app/(auth)/login/page.tsx`
- `app/(protected)/layout.tsx`
- `components/shared/app-shell.tsx`

Authenticated users land in the protected dashboard and navigate to personal requests, reviewer request queues, expenses, notifications, profile maintenance, and payment-QR lookup.

#### Authentication and Identity
Authentication is implemented as a feature with server actions for login, password recovery/reset, and password changes. Session and authorization concerns are centralized under `lib/auth`, rather than embedded in individual pages. An auth confirmation route supports provider callback/token confirmation flows.

Key paths:
- `features/auth/actions.ts`
- `lib/auth/session.ts`
- `lib/auth/permissions.ts`
- `app/auth/confirm/route.ts`

#### Payment Request Lifecycle
`features/payment-requests` is the dominant business domain. It owns request schemas/types, read queries, write actions, and UI for request creation/editing, details, status timeline, review, deletion, attachments, bills, and QR proof uploads. Page routes act mainly as workflow entry points for an employee’s requests and a reviewer’s queue.

Main lifecycle surfaces:
- `features/payment-requests/actions.ts`
- `features/payment-requests/queries.ts`
- `features/payment-requests/components/request-form.tsx`
- `app/(protected)/my-requests/[id]/page.tsx`
- `app/(protected)/requests/[id]/page.tsx`

Control flow is: authenticated user → page/query loads request data → form or review component invokes server action → persistence/storage updates → status/detail/list views refresh. Employee-owned routes (`my-requests`) and organization review routes (`requests`) form an important permissions boundary.

#### Expenses, Documents, and Export
Expense reporting is derived from payment-request data. The application supports filtering request/expense lists, storing bill and QR artifacts, showing galleries, and producing a downloadable monthly export from an Excel template. The export Route Handler is a server-side delivery boundary.

Key paths:
- `app/(protected)/expenses/export/route.ts`
- `features/payment-requests/expense-export.ts`
- `features/payment-requests/payment-bill-storage.ts`
- `features/payment-requests/templates/expense-monthly-export-template.xlsx`

#### Supabase Data and External Integration
Supabase is the material backend integration, with separate browser, server, and proxy clients. Generated database types establish the application’s persistence contract. Supabase likely supplies authentication, relational data, and object storage used by payment evidence modules.

Backend integration paths:
- `lib/supabase/browser.ts`
- `lib/supabase/server.ts`
- `lib/supabase/proxy.ts`
- `types/database.ts`

An inbound webhook endpoint handles notification-email events, separating external delivery/integration traffic from interactive application routes:
- `app/api/webhooks/notification-email/route.ts`

#### Notifications and Payment QR
Notifications are a self-contained domain with queries, actions, service logic, provider state, and bell/list UI; it is surfaced globally and on its own protected page. Payment QR is a distinct lookup/selection workflow that loads unpaid requests, selects employee/request context, and renders QR-related payment information.

Key paths:
- `features/notifications/service.ts`
- `features/notifications/components/notifications-provider.tsx`
- `features/payment-qr/queries.ts`
- `app/(protected)/payment-qr/page.tsx`

Main entry points: [`lib/supabase/server.ts`](https://github.com/dncmaduro/dntt/blob/main/lib/supabase/server.ts) (Supabase), [`lib/auth/session.ts`](https://github.com/dncmaduro/dntt/blob/main/lib/auth/session.ts) (Session & permissions), [`features/payment-requests/queries.ts`](https://github.com/dncmaduro/dntt/blob/main/features/payment-requests/queries.ts) (Request queries), [`proxy.ts`](https://github.com/dncmaduro/dntt/blob/main/proxy.ts) (Request proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access & shell"]
  node_root_layout["Root layout<br/>Next.js layout<br/>[layout.tsx]"]
  node_proxy{{"Request proxy<br/>middleware<br/>[proxy.ts]"}}
  node_login["Login<br/>public route<br/>[page.tsx]"]
  node_auth_actions["Auth actions<br/>Server Actions<br/>[actions.ts]"]
  node_session["Session &amp; permissions<br/>auth services<br/>[session.ts]"]
  node_protected_layout["Protected layout<br/>authorization boundary<br/>[layout.tsx]"]
  node_app_shell["Application shell<br/>shared UI<br/>[app-shell.tsx]"]
  node_auth_confirm{{"Auth confirmation<br/>Route Handler<br/>[route.ts]"}}
end

subgraph group_requests["Payment requests"]
  node_request_queries["Request queries<br/>data reads<br/>[queries.ts]"]
  node_request_actions["Request actions<br/>Server Actions<br/>[actions.ts]"]
  node_request_form["Request form<br/>workflow UI<br/>[request-form.tsx]"]
  node_my_request_detail["My request detail<br/>employee route<br/>[page.tsx]"]
  node_review_request_detail["Review request detail<br/>reviewer route<br/>[page.tsx]"]
end

subgraph group_reporting["Expenses &amp; export"]
  node_evidence_storage["Bill evidence storage<br/>object storage adapter"]
  node_expense_export["Monthly expense export<br/>export service<br/>[expense-export.ts]"]
  node_export_route{{"Expense export endpoint<br/>Route Handler<br/>[route.ts]"}}
end

subgraph group_engagement["Notifications &amp; QR"]
  node_notification_service["Notification service<br/>domain service<br/>[service.ts]"]
  node_notifications_provider["Notifications provider<br/>global UI state"]
  node_notification_webhook{{"Notification email webhook<br/>inbound Route Handler<br/>[route.ts]"}}
  node_payment_qr_queries["Payment QR queries<br/>lookup reads<br/>[queries.ts]"]
  node_payment_qr_page["Payment QR lookup<br/>protected route<br/>[page.tsx]"]
end

subgraph group_backend["Supabase backend"]
  node_supabase[("Supabase<br/>auth, database &amp; storage<br/>[server.ts]")]
  node_database_types["Database contract<br/>generated types<br/>[database.ts]"]
end

node_root_layout --> node_proxy
node_login -->|"submits credentials"| node_auth_actions
node_auth_actions -->|"creates session"| node_session
node_auth_confirm -->|"confirms identity"| node_session
node_proxy -->|"refreshes and checks"| node_session
node_proxy -->|"permits protected access"| node_protected_layout
node_protected_layout -->|"renders"| node_app_shell
node_session -->|"uses auth"| node_supabase
node_request_queries -->|"reads requests"| node_supabase
node_request_actions -->|"persists lifecycle"| node_supabase
node_my_request_detail -->|"loads owned request"| node_request_queries
node_my_request_detail -->|"renders workflow"| node_request_form
node_review_request_detail -->|"loads review data"| node_request_queries
node_request_form -->|"submits changes"| node_request_actions
node_request_actions -->|"stores artifacts"| node_evidence_storage
node_evidence_storage -->|"uses object storage"| node_supabase
node_export_route -->|"generates download"| node_expense_export
node_expense_export -->|"derives expense data"| node_request_queries
node_notifications_provider -->|"loads and updates"| node_notification_service
node_notification_service -->|"persists notifications"| node_supabase
node_notification_webhook -->|"receives email events"| node_notification_service
node_payment_qr_page -->|"loads unpaid requests"| node_payment_qr_queries
node_payment_qr_queries -->|"reads payment context"| node_supabase
node_database_types -.->|"types persistence"| node_supabase

click node_root_layout "https://github.com/dncmaduro/dntt/blob/main/app/layout.tsx"
click node_proxy "https://github.com/dncmaduro/dntt/blob/main/proxy.ts"
click node_login "https://github.com/dncmaduro/dntt/blob/main/app/(auth)/login/page.tsx"
click node_auth_actions "https://github.com/dncmaduro/dntt/blob/main/features/auth/actions.ts"
click node_session "https://github.com/dncmaduro/dntt/blob/main/lib/auth/session.ts"
click node_protected_layout "https://github.com/dncmaduro/dntt/blob/main/app/(protected)/layout.tsx"
click node_app_shell "https://github.com/dncmaduro/dntt/blob/main/components/shared/app-shell.tsx"
click node_auth_confirm "https://github.com/dncmaduro/dntt/blob/main/app/auth/confirm/route.ts"
click node_request_queries "https://github.com/dncmaduro/dntt/blob/main/features/payment-requests/queries.ts"
click node_request_actions "https://github.com/dncmaduro/dntt/blob/main/features/payment-requests/actions.ts"
click node_request_form "https://github.com/dncmaduro/dntt/blob/main/features/payment-requests/components/request-form.tsx"
click node_my_request_detail "https://github.com/dncmaduro/dntt/blob/main/app/(protected)/my-requests/%5Bid%5D/page.tsx"
click node_review_request_detail "https://github.com/dncmaduro/dntt/blob/main/app/(protected)/requests/%5Bid%5D/page.tsx"
click node_evidence_storage "https://github.com/dncmaduro/dntt/blob/main/features/payment-requests/payment-bill-storage.ts"
click node_expense_export "https://github.com/dncmaduro/dntt/blob/main/features/payment-requests/expense-export.ts"
click node_export_route "https://github.com/dncmaduro/dntt/blob/main/app/(protected)/expenses/export/route.ts"
click node_notification_service "https://github.com/dncmaduro/dntt/blob/main/features/notifications/service.ts"
click node_notifications_provider "https://github.com/dncmaduro/dntt/blob/main/features/notifications/components/notifications-provider.tsx"
click node_notification_webhook "https://github.com/dncmaduro/dntt/blob/main/app/api/webhooks/notification-email/route.ts"
click node_payment_qr_queries "https://github.com/dncmaduro/dntt/blob/main/features/payment-qr/queries.ts"
click node_payment_qr_page "https://github.com/dncmaduro/dntt/blob/main/app/(protected)/payment-qr/page.tsx"
click node_supabase "https://github.com/dncmaduro/dntt/blob/main/lib/supabase/server.ts"
click node_database_types "https://github.com/dncmaduro/dntt/blob/main/types/database.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_root_layout,node_proxy,node_login,node_auth_actions,node_session,node_protected_layout,node_app_shell,node_auth_confirm toneBlue
class node_request_queries,node_request_actions,node_request_form,node_my_request_detail,node_review_request_detail toneAmber
class node_evidence_storage,node_expense_export,node_export_route toneMint
class node_notification_service,node_notifications_provider,node_notification_webhook,node_payment_qr_queries,node_payment_qr_page toneRose
class node_supabase,node_database_types toneIndigo
```

## Components

### Access & shell

- [Root layout](https://github.com/dncmaduro/dntt/blob/main/app/layout.tsx): Next.js layout · `app/layout.tsx`
- [Request proxy](https://github.com/dncmaduro/dntt/blob/main/proxy.ts): middleware · Refreshes sessions and enforces request-level access. · `proxy.ts`
- [Login](https://github.com/dncmaduro/dntt/blob/main/app/(auth)/login/page.tsx): public route · `app/(auth)/login/page.tsx`
- [Auth actions](https://github.com/dncmaduro/dntt/blob/main/features/auth/actions.ts): Server Actions · Handles login and password recovery flows. · `features/auth/actions.ts`
- [Session & permissions](https://github.com/dncmaduro/dntt/blob/main/lib/auth/session.ts): auth services · `lib/auth/session.ts`
- [Protected layout](https://github.com/dncmaduro/dntt/blob/main/app/(protected)/layout.tsx): authorization boundary · Gates authenticated operational routes. · `app/(protected)/layout.tsx`
- [Application shell](https://github.com/dncmaduro/dntt/blob/main/components/shared/app-shell.tsx): shared UI · `components/shared/app-shell.tsx`
- [Auth confirmation](https://github.com/dncmaduro/dntt/blob/main/app/auth/confirm/route.ts): Route Handler · Completes provider callback or token confirmation. · `app/auth/confirm/route.ts`

### Payment requests

- [Request queries](https://github.com/dncmaduro/dntt/blob/main/features/payment-requests/queries.ts): data reads · `features/payment-requests/queries.ts`
- [Request actions](https://github.com/dncmaduro/dntt/blob/main/features/payment-requests/actions.ts): Server Actions · Writes requests, reviews, status, and evidence changes. · `features/payment-requests/actions.ts`
- [Request form](https://github.com/dncmaduro/dntt/blob/main/features/payment-requests/components/request-form.tsx): workflow UI · `features/payment-requests/components/request-form.tsx`
- [My request detail](https://github.com/dncmaduro/dntt/blob/main/app/(protected)/my-requests/%5Bid%5D/page.tsx): employee route · Employee-owned request workflow. · `app/(protected)/my-requests/[id]/page.tsx`
- [Review request detail](https://github.com/dncmaduro/dntt/blob/main/app/(protected)/requests/%5Bid%5D/page.tsx): reviewer route · Organization review workflow. · `app/(protected)/requests/[id]/page.tsx`

### Expenses & export

- [Bill evidence storage](https://github.com/dncmaduro/dntt/blob/main/features/payment-requests/payment-bill-storage.ts): object storage adapter · `features/payment-requests/payment-bill-storage.ts`
- [Monthly expense export](https://github.com/dncmaduro/dntt/blob/main/features/payment-requests/expense-export.ts): export service · Builds a workbook from the monthly export template. · `features/payment-requests/expense-export.ts`
- [Expense export endpoint](https://github.com/dncmaduro/dntt/blob/main/app/(protected)/expenses/export/route.ts): Route Handler · Delivers the downloadable monthly export. · `app/(protected)/expenses/export/route.ts`

### Notifications & QR

- [Notification service](https://github.com/dncmaduro/dntt/blob/main/features/notifications/service.ts): domain service · `features/notifications/service.ts`
- [Notifications provider](https://github.com/dncmaduro/dntt/blob/main/features/notifications/components/notifications-provider.tsx): global UI state · Supplies bell and notification list state. · `features/notifications/components/notifications-provider.tsx`
- [Notification email webhook](https://github.com/dncmaduro/dntt/blob/main/app/api/webhooks/notification-email/route.ts): inbound Route Handler · `app/api/webhooks/notification-email/route.ts`
- [Payment QR queries](https://github.com/dncmaduro/dntt/blob/main/features/payment-qr/queries.ts): lookup reads · Loads unpaid requests and payment context. · `features/payment-qr/queries.ts`
- [Payment QR lookup](https://github.com/dncmaduro/dntt/blob/main/app/(protected)/payment-qr/page.tsx): protected route · `app/(protected)/payment-qr/page.tsx`

### Supabase backend

- [Supabase](https://github.com/dncmaduro/dntt/blob/main/lib/supabase/server.ts): auth, database & storage · Backend persistence and identity platform. · `lib/supabase/server.ts`
- [Database contract](https://github.com/dncmaduro/dntt/blob/main/types/database.ts): generated types · `types/database.ts`

## Connections

- Root layout → Request proxy
- Login → Auth actions: submits credentials
- Auth actions → Session & permissions: creates session
- Auth confirmation → Session & permissions: confirms identity
- Request proxy → Session & permissions: refreshes and checks
- Request proxy → Protected layout: permits protected access
- Protected layout → Application shell: renders
- Session & permissions → Supabase: uses auth
- Request queries → Supabase: reads requests
- Request actions → Supabase: persists lifecycle
- My request detail → Request queries: loads owned request
- My request detail → Request form: renders workflow
- Review request detail → Request queries: loads review data
- Request form → Request actions: submits changes
- Request actions → Bill evidence storage: stores artifacts
- Bill evidence storage → Supabase: uses object storage
- Expense export endpoint → Monthly expense export: generates download
- Monthly expense export → Request queries: derives expense data
- Notifications provider → Notification service: loads and updates
- Notification service → Supabase: persists notifications
- Notification email webhook → Notification service: receives email events
- Payment QR lookup → Payment QR queries: loads unpaid requests
- Payment QR queries → Supabase: reads payment context
- Database contract → Supabase: types persistence