How shadab-gtf/report-manager-next works
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: manager Manager · app App Router · api API Routes · auth Auth
Components 18
Presentation
Route layer, shared shell, and UI composition
- App Router · Route-level pages and API entry points
app - API Routes · Thin backend endpoints for auth and notifications
app/api - Shell UI · App shell, sections, and reusable UI primitives
components
Feature Modules
Domain-specific business logic and feature components
- Auth · Login, signup, biometrics, and session flows
modules/auth - Reports · Report creation, drafts, history, and submission
modules/reports - Manager · Analytics, review, team views, and oversight tools
modules/manager - Team Data · Shared team data access used across employee and manager views
modules/team
Infrastructure
Shared services, state, and security helpers
- Session Security · Signed cookie integrity for auth/session state
lib/security/cookie-signer.ts - Dashboard API · Centralized dashboard data fetching
lib/api/dashboard.ts - Client Store · Global store and notification state
store - Providers · Client providers and session hydration
components/providers - Report Repo · Report persistence and database abstraction
modules/reports/services/report-repository.ts - Team Repo · Team data repository shared by the app
modules/team/services/team-repository.ts - Manager Services · Analytics, team, and review service functions
modules/manager/services - Email Template · Report email generation and formatting
modules/reports/utils/email-template.ts - Shared Types · Auth, dashboard, report, and team data contracts
types
Platform
PWA assets and application-wide runtime support
- PWA Layer · Manifest, service worker, offline and install UX
app/manifest.ts - Service Worker · Offline caching and PWA runtime support
public/sw.js
Connections 21
- 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