# shadab-gtf/report-manager-next architecture

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

- Interactive diagram: https://gitdiagram.com/shadab-gtf/report-manager-next
- Repository: https://github.com/shadab-gtf/report-manager-next

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** application with a clear split between route-level pages under `app/` and feature-centric code under `modules/`.
   - The repository is organized around three main product areas: **auth/onboarding**, **employee reporting**, and **manager oversight/analytics**.

2. **Route layer vs. feature layer**
   - `app/` contains the navigation and page composition for the UI, plus a small set of API routes.
   - `modules/` contains the actual business logic, feature-specific components, hooks, services, and types.
   - For an architecture diagram, treat `app/` as the presentation/routing boundary and `modules/` as the domain/application layer.

3. **Authentication subsystem**
   - Auth flows live in `app/login`, `app/signup`, `app/forgot-password`, `app/verify-email`, and `app/api/auth/login`.
   - The `modules/auth` package includes the login/signup UI, form schemas, session client, biometric preference handling, and WebAuthn-related helpers.
   - `lib/security/cookie-signer.ts` suggests session or token integrity is enforced with signed cookies rather than relying only on client state.

4. **Reporting subsystem**
   - Employee report creation and review are centered in `app/reports/*` and backed by `modules/reports`.
   - Important report flows include:
     - creating a report (`/reports/create`)
     - managing drafts (`/reports/drafts`)
     - viewing report history (`/reports/history`)
     - viewing a single report (`/reports/[id]`)
   - `modules/reports` contains the report builder UI, draft handling hook, repository/database abstraction, and email template generation.

5. **Manager subsystem**
   - Manager-facing functionality is grouped under `app/manager/*` and `modules/manager`.
   - Pages cover analytics, missing reports, team views, report review, and employee history.
   - `modules/manager` separates presentation components from hooks and services, which suggests data is loaded through reusable service functions rather than directly in page components.

6. **Team and employee data**
   - Team-related screens live in `app/team`, `app/team/reports`, and `app/manager/team/[employeeId]`.
   - `modules/team` and `modules/manager/services/team-service.ts` / `team-repository.ts` indicate a shared team data model used by both employees and managers.
   - The dynamic employee route plus history view suggests a per-employee detail boundary that likely aggregates report history and status.

7. **Server/API boundary**
   - The only explicit backend entry points visible are:
     - `app/api/auth/login/route.ts`
     - `app/api/send-report/route.ts`
     - `app/api/send-nudge/route.ts`
   - These endpoints likely act as thin server adapters for auth, report delivery, and reminder/notification actions.
   - The rest of the app appears to rely on page/server rendering and feature services rather than a large standalone API surface.

8. **Shared UI and shell**
   - `components/sections` contains higher-level reusable page sections such as dashboard hero, metrics, recent activity, workflow, and app shell.
   - `components/ui` contains generic app-wide primitives like metric cards, status pills, offline banner, install prompt, notification center, and PWA registry.
   - This indicates a shared design system layer used across multiple routes rather than duplicated per feature.

9. **State management and client hydration**
   - `store/store.ts` and `store/hooks.ts` provide a global state layer; `modules/notifications/store/notification-store.ts` suggests notifications are managed centrally.
   - `components/providers/app-providers.tsx` and `session-hydrator.tsx` are the key glue for wiring client-side providers and restoring session state.
   - This is important architecturally: server-rendered pages likely hydrate into a client state shell for auth/session/notification continuity.

10. **Data access and service boundaries**
   - `modules/*/services` and `modules/reports/services/report-repository.ts` indicate an explicit service/repository split.
   - `lib/api/dashboard.ts` and `modules/manager/services/analytics-service.ts` suggest data fetching is centralized behind service functions rather than embedded in components.
   - `types/` holds shared contracts for auth, dashboard, report, and team data, which helps keep route, service, and UI layers aligned.

11. **Progressive web app and offline support**
   - The presence of `public/sw.js`, `app/manifest.ts`, `components/ui/pwa-registry.tsx`, `offline-banner.tsx`, and `install-prompt.tsx` shows the app is designed as a **PWA**.
   - That means the architecture includes offline awareness, installability, and user-facing network status handling as first-class concerns, not just a visual enhancement.

12. **Testing and quality boundaries**
   - Tests are concentrated around core logic: `cookie-signer`, `email-template`, and manager behavior.
   - This suggests the most critical non-UI logic is in the security, email/reporting, and manager service layers.
   - For a diagram, these tests sit beside the domain services they validate, not the route layer.

13. **Likely end-to-end data flow**
   - User signs in through auth pages/API, session is established via signed cookie/session client.
   - Employees build or submit reports through the reports feature; report data moves through report hooks/services/repository and may trigger email generation or submission via API routes.
   - Managers consume the same underlying team/report data through analytics, review, and missing-report views, using manager services and dashboard APIs.
   - Notifications, nudges, and offline/PWA behavior cross-cut these flows through shared store and UI infrastructure.

14. **Useful diagram boundaries**
   - A good architecture diagram would separate:
     - **Presentation**: `app/`, `components/`
     - **Feature/domain logic**: `modules/`
     - **Infrastructure/helpers**: `lib/`, `store/`, `types/`
     - **Server entry points**: `app/api/*`
     - **Platform extras**: PWA/offline/notifications
   - The system is not a generic CRUD app; it is a role-based workflow app with distinct employee and manager experiences sharing a common data model.

Main entry points: [`modules/manager`](https://github.com/shadab-gtf/report-manager-next/tree/main/modules/manager) (Manager), [`app`](https://github.com/shadab-gtf/report-manager-next/tree/main/app) (App Router), [`app/api`](https://github.com/shadab-gtf/report-manager-next/tree/main/app/api) (API Routes), [`modules/auth`](https://github.com/shadab-gtf/report-manager-next/tree/main/modules/auth) (Auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_app_router["App Router<br/>nextjs routes"]
  node_app_api["API Routes<br/>server adapters"]
  node_shared_shell["Shell UI<br/>layout components"]
end

subgraph group_features["Feature Modules"]
  node_auth_module["Auth<br/>feature module"]
  node_reports_module["Reports<br/>feature module"]
  node_manager_module["Manager<br/>feature module"]
  node_team_module["Team Data<br/>domain repository"]
end

subgraph group_infrastructure["Infrastructure"]
  node_session_security{{"Session Security<br/>security helper<br/>[cookie-signer.ts]"}}
  node_dashboard_api["Dashboard API<br/>data adapter<br/>[dashboard.ts]"]
  node_client_store["Client Store<br/>state layer"]
  node_app_providers["Providers<br/>hydration glue"]
  node_report_repo[("Report Repo")]
  node_team_repo[("Team Repo<br/>[team-repository.ts]")]
  node_manager_services["Manager Services<br/>service layer"]
  node_report_email["Email Template<br/>[email-template.ts]"]
  node_types_shared["Shared Types<br/>contracts"]
end

subgraph group_platform["Platform"]
  node_pwa_platform["PWA Layer<br/>platform support<br/>[manifest.ts]"]
  node_public_sw["Service Worker<br/>runtime asset<br/>[sw.js]"]
end

node_app_router -->|"renders"| node_auth_module
node_app_router -->|"renders"| node_reports_module
node_app_router -->|"renders"| node_manager_module
node_app_router -->|"composes"| node_shared_shell
node_app_router -->|"exposes"| node_app_api
node_app_api -->|"auth"| node_auth_module
node_app_api -->|"submit"| node_reports_module
node_app_api -->|"notify"| node_manager_module
node_auth_module -->|"secures"| node_session_security
node_auth_module -->|"hydrates"| node_app_providers
node_reports_module -->|"persists"| node_report_repo
node_reports_module -->|"formats"| node_report_email
node_manager_module -->|"loads"| node_manager_services
node_manager_module -->|"reads"| node_team_repo
node_manager_module -->|"fetches"| node_dashboard_api
node_manager_module -->|"models"| node_types_shared
node_team_module -->|"backed by"| node_team_repo
node_shared_shell -->|"uses"| node_client_store
node_app_providers -->|"provides"| node_client_store
node_pwa_platform -->|"registers"| node_public_sw
node_shared_shell -->|"supports"| node_pwa_platform

click node_app_router "https://github.com/shadab-gtf/report-manager-next/tree/main/app"
click node_app_api "https://github.com/shadab-gtf/report-manager-next/tree/main/app/api"
click node_shared_shell "https://github.com/shadab-gtf/report-manager-next/tree/main/components"
click node_auth_module "https://github.com/shadab-gtf/report-manager-next/tree/main/modules/auth"
click node_reports_module "https://github.com/shadab-gtf/report-manager-next/tree/main/modules/reports"
click node_manager_module "https://github.com/shadab-gtf/report-manager-next/tree/main/modules/manager"
click node_team_module "https://github.com/shadab-gtf/report-manager-next/tree/main/modules/team"
click node_session_security "https://github.com/shadab-gtf/report-manager-next/blob/main/lib/security/cookie-signer.ts"
click node_dashboard_api "https://github.com/shadab-gtf/report-manager-next/blob/main/lib/api/dashboard.ts"
click node_client_store "https://github.com/shadab-gtf/report-manager-next/tree/main/store"
click node_app_providers "https://github.com/shadab-gtf/report-manager-next/tree/main/components/providers"
click node_report_repo "https://github.com/shadab-gtf/report-manager-next/blob/main/modules/reports/services/report-repository.ts"
click node_team_repo "https://github.com/shadab-gtf/report-manager-next/blob/main/modules/team/services/team-repository.ts"
click node_manager_services "https://github.com/shadab-gtf/report-manager-next/tree/main/modules/manager/services"
click node_report_email "https://github.com/shadab-gtf/report-manager-next/blob/main/modules/reports/utils/email-template.ts"
click node_types_shared "https://github.com/shadab-gtf/report-manager-next/tree/main/types"
click node_pwa_platform "https://github.com/shadab-gtf/report-manager-next/blob/main/app/manifest.ts"
click node_public_sw "https://github.com/shadab-gtf/report-manager-next/blob/main/public/sw.js"

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_app_router,node_app_api,node_shared_shell toneBlue
class node_auth_module,node_reports_module,node_manager_module,node_team_module toneAmber
class node_session_security,node_dashboard_api,node_client_store,node_app_providers,node_report_repo,node_team_repo,node_manager_services,node_report_email,node_types_shared toneMint
class node_pwa_platform,node_public_sw toneRose
```

## Components

### Presentation

Route layer, shared shell, and UI composition

- [App Router](https://github.com/shadab-gtf/report-manager-next/tree/main/app): nextjs routes · Route-level pages and API entry points · `app`
- [API Routes](https://github.com/shadab-gtf/report-manager-next/tree/main/app/api): server adapters · Thin backend endpoints for auth and notifications · `app/api`
- [Shell UI](https://github.com/shadab-gtf/report-manager-next/tree/main/components): layout components · App shell, sections, and reusable UI primitives · `components`

### Feature Modules

Domain-specific business logic and feature components

- [Auth](https://github.com/shadab-gtf/report-manager-next/tree/main/modules/auth): feature module · Login, signup, biometrics, and session flows · `modules/auth`
- [Reports](https://github.com/shadab-gtf/report-manager-next/tree/main/modules/reports): feature module · Report creation, drafts, history, and submission · `modules/reports`
- [Manager](https://github.com/shadab-gtf/report-manager-next/tree/main/modules/manager): feature module · Analytics, review, team views, and oversight tools · `modules/manager`
- [Team Data](https://github.com/shadab-gtf/report-manager-next/tree/main/modules/team): domain repository · Shared team data access used across employee and manager views · `modules/team`

### Infrastructure

Shared services, state, and security helpers

- [Session Security](https://github.com/shadab-gtf/report-manager-next/blob/main/lib/security/cookie-signer.ts): security helper · Signed cookie integrity for auth/session state · `lib/security/cookie-signer.ts`
- [Dashboard API](https://github.com/shadab-gtf/report-manager-next/blob/main/lib/api/dashboard.ts): data adapter · Centralized dashboard data fetching · `lib/api/dashboard.ts`
- [Client Store](https://github.com/shadab-gtf/report-manager-next/tree/main/store): state layer · Global store and notification state · `store`
- [Providers](https://github.com/shadab-gtf/report-manager-next/tree/main/components/providers): hydration glue · Client providers and session hydration · `components/providers`
- [Report Repo](https://github.com/shadab-gtf/report-manager-next/blob/main/modules/reports/services/report-repository.ts): repository · Report persistence and database abstraction · `modules/reports/services/report-repository.ts`
- [Team Repo](https://github.com/shadab-gtf/report-manager-next/blob/main/modules/team/services/team-repository.ts): repository · Team data repository shared by the app · `modules/team/services/team-repository.ts`
- [Manager Services](https://github.com/shadab-gtf/report-manager-next/tree/main/modules/manager/services): service layer · Analytics, team, and review service functions · `modules/manager/services`
- [Email Template](https://github.com/shadab-gtf/report-manager-next/blob/main/modules/reports/utils/email-template.ts): utility · Report email generation and formatting · `modules/reports/utils/email-template.ts`
- [Shared Types](https://github.com/shadab-gtf/report-manager-next/tree/main/types): contracts · Auth, dashboard, report, and team data contracts · `types`

### Platform

PWA assets and application-wide runtime support

- [PWA Layer](https://github.com/shadab-gtf/report-manager-next/blob/main/app/manifest.ts): platform support · Manifest, service worker, offline and install UX · `app/manifest.ts`
- [Service Worker](https://github.com/shadab-gtf/report-manager-next/blob/main/public/sw.js): runtime asset · Offline caching and PWA runtime support · `public/sw.js`

## Connections

- App Router → Auth: renders · Auth and onboarding pages are composed from auth feature code
- App Router → Reports: renders · Report pages use the reports feature module
- App Router → Manager: renders · Manager pages use the manager feature module
- App Router → Shell UI: composes · Routes are wrapped in shared sections and UI primitives
- App Router → API Routes: exposes · Route layer includes API endpoints alongside pages
- API Routes → Auth: auth · Login endpoint delegates to auth logic
- API Routes → Reports: submit · Report delivery endpoint connects to report flows
- API Routes → Manager: notify · Nudge endpoint supports manager-driven reminders
- Auth → Session Security: secures · Auth state is protected by signed cookie integrity
- Auth → Providers: hydrates · Session state is restored into the client shell
- Reports → Report Repo: persists · Reports are saved and loaded through a repository boundary
- Reports → Email Template: formats · Report output can be converted into email content
- Manager → Manager Services: loads · Manager UI consumes reusable service functions
- Manager → Team Repo: reads · Team and employee views rely on shared team data access
- Manager → Dashboard API: fetches · Analytics and dashboard views use centralized data adapters
- Manager → Shared Types: models · Manager flows share contracts with the rest of the app
- Team Data → Team Repo: backed by · Team domain access is implemented through a repository
- Shell UI → Client Store: uses · UI shell integrates global state and notifications
- Providers → Client Store: provides · Provider layer wires global client state
- PWA Layer → Service Worker: registers · PWA layer is backed by the service worker asset
- Shell UI → PWA Layer: supports · Shared UI includes offline and install surfaces