# pittu777/health architecture

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

- Interactive diagram: https://gitdiagram.com/pittu777/health
- Repository: https://github.com/pittu777/health

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** project in TypeScript.
   - The architecture is centered on an **authentication flow** rather than a broad application domain.
   - The repo is split into **route handlers**, **feature components**, **shared libraries**, **middleware**, and **tests**.

2. **UI route layer**
   - `src/app/page.tsx` is the top-level landing page.
   - `src/app/(auth)/login/page.tsx` and `src/app/(auth)/register/page.tsx` define the public auth screens.
   - `src/app/layout.tsx` and `src/app/globals.css` provide the application shell and global styling.

3. **API boundary**
   - `src/app/api/auth/login/route.ts`
   - `src/app/api/auth/logout/route.ts`
   - `src/app/api/auth/refresh/route.ts`
   - `src/app/api/auth/register/route.ts`
   - These route handlers form the server-side contract for authentication operations and are the main backend entry points.

4. **Auth flow and session lifecycle**
   - The presence of **login, register, logout, and refresh** endpoints indicates a session/token-based auth lifecycle.
   - `src/lib/auth.ts` and `src/lib/auth/session.ts` appear to hold shared auth/session logic used by both route handlers and UI behavior.
   - `src/feature/auth/SessionRefresh.tsx` suggests the client participates in keeping sessions alive or refreshing credentials.

5. **Feature-oriented auth UI**
   - `src/feature/auth/AuthForm.tsx`, `Login.tsx`, `Register.tsx`, and `Logout.tsx` are the auth-specific presentation and interaction layer.
   - This feature directory separates auth workflows from route definitions, which keeps the UI reusable and easier to diagram as a distinct subsystem.

6. **Client-side auth state**
   - `src/feature/hooks/useAuth.ts` is the client-side hook boundary for auth state/behavior.
   - This likely coordinates user/session status across components rather than embedding auth checks directly in pages.

7. **Middleware and protection**
   - `src/middleware/auth.middleware.ts` is a request-level guard layer.
   - It likely enforces access control or session validation before requests reach protected pages or APIs, making it a key architectural boundary between public and protected areas.

8. **Domain and persistence layer**
   - `src/models/user.model.ts` represents the user domain entity/model.
   - `src/config/db.ts` indicates a server-side database configuration boundary.
   - Together these suggest the auth routes talk to a persistence layer through a model/config abstraction rather than directly from UI code.

9. **Shared utilities and errors**
   - `src/lib/AppError.ts` provides application-specific error handling.
   - `src/lib/utils.ts` contains shared helper logic.
   - These support consistent server/client behavior without coupling auth features to framework-specific details.

10. **Reusable UI primitives**
   - `src/components/ui/button.tsx` and `src/components/ui/input.tsx` are shared design-system style components.
   - `components.json` suggests a component-scaffolding or design-system setup, likely used to standardize form controls across auth pages.

11. **Testing boundary**
   - `tests/auth/login.spec.ts` and `tests/auth/register.spec.ts` are end-to-end or browser-style tests.
   - `playwright.config.ts` confirms Playwright is used to validate auth flows from the user’s perspective, which means the test layer exercises the public pages and API-backed behavior together.

12. **How data moves through the system**
   - A user interacts with the auth pages in `src/app/(auth)/...`.
   - UI components in `src/feature/auth` submit to `/api/auth/*` route handlers.
   - Those handlers use shared auth/session logic, the user model, and DB configuration to validate or mutate user/session state.
   - Middleware can intercept requests to enforce auth status.
   - Client-side hooks/components then reflect or refresh that session state back in the UI.

13. **Key diagram boundaries**
   - **Browser/UI boundary:** app pages, feature components, hooks, and reusable UI primitives.
   - **Server/API boundary:** Next.js route handlers under `/api/auth`.
   - **Security boundary:** middleware and session refresh logic.
   - **Persistence boundary:** DB config plus user model.
   - **Quality boundary:** Playwright auth specs validating the end-to-end flow.

Main entry points: [`src/lib/auth.ts`](https://github.com/pittu777/health/blob/main/src/lib/auth.ts) (Auth Core), [`src/app/api/auth/login/route.ts`](https://github.com/pittu777/health/blob/main/src/app/api/auth/login/route.ts) (Login API), [`src/app/api/auth/register/route.ts`](https://github.com/pittu777/health/blob/main/src/app/api/auth/register/route.ts) (Register API), [`src/app/layout.tsx`](https://github.com/pittu777/health/blob/main/src/app/layout.tsx) (App Shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App Router"]
  node_node_page["Home<br/>route page<br/>[page.tsx]"]
  node_node_login_page["Login Page<br/>route page<br/>[page.tsx]"]
  node_node_register_page["Register Page<br/>route page<br/>[page.tsx]"]
  node_node_layout["App Shell<br/>layout<br/>[layout.tsx]"]
  node_node_styles["Globals<br/>styles<br/>[globals.css]"]
  node_node_api_login["Login API<br/>route handler<br/>[route.ts]"]
  node_node_api_logout["Logout API<br/>route handler<br/>[route.ts]"]
  node_node_api_refresh["Refresh API<br/>route handler<br/>[route.ts]"]
  node_node_api_register["Register API<br/>route handler<br/>[route.ts]"]
end

subgraph group_group_feature["Auth Feature"]
  node_node_auth_form["Auth Form<br/>feature component<br/>[AuthForm.tsx]"]
  node_node_feature_login["Login UI<br/>feature component<br/>[Login.tsx]"]
  node_node_feature_register["Register UI<br/>feature component<br/>[Register.tsx]"]
  node_node_logout["Logout UI<br/>feature component<br/>[Logout.tsx]"]
  node_node_session_refresh["Session Refresh<br/>client session<br/>[SessionRefresh.tsx]"]
  node_node_use_auth["useAuth<br/>hook<br/>[useAuth.ts]"]
end

subgraph group_group_server["Server Core"]
  node_node_auth_lib["Auth Core<br/>shared auth<br/>[auth.ts]"]
  node_node_session_lib["Session Logic<br/>session helpers<br/>[session.ts]"]
  node_node_db[("DB Config<br/>database config<br/>[db.ts]")]
  node_node_user_model{{"User Model<br/>domain model<br/>[user.model.ts]"}}
  node_node_error["App Error<br/>error handling<br/>[AppError.ts]"]
  node_node_utils["Utils<br/>shared helpers<br/>[utils.ts]"]
  node_node_middleware["Auth Middleware<br/>request guard<br/>[auth.middleware.ts]"]
end

subgraph group_group_quality["Tests"]
  node_node_test_login["Login Spec<br/>playwright test<br/>[login.spec.ts]"]
  node_node_test_register["Register Spec<br/>playwright test<br/>[register.spec.ts]"]
end

node_node_layout -->|"wraps"| node_node_page
node_node_layout -->|"wraps"| node_node_login_page
node_node_layout -->|"wraps"| node_node_register_page
node_node_styles -->|"styles"| node_node_layout
node_node_login_page -->|"renders"| node_node_feature_login
node_node_register_page -->|"renders"| node_node_feature_register
node_node_feature_login -->|"uses"| node_node_auth_form
node_node_feature_register -->|"uses"| node_node_auth_form
node_node_feature_login -->|"submits to"| node_node_api_login
node_node_feature_register -->|"submits to"| node_node_api_register
node_node_logout -->|"calls"| node_node_api_logout
node_node_session_refresh -->|"refreshes"| node_node_api_refresh
node_node_use_auth -->|"coordinates"| node_node_session_refresh
node_node_api_login -->|"uses"| node_node_auth_lib
node_node_api_register -->|"uses"| node_node_auth_lib
node_node_api_logout -->|"uses"| node_node_session_lib
node_node_api_refresh -->|"uses"| node_node_session_lib
node_node_auth_lib -->|"depends on"| node_node_session_lib
node_node_auth_lib -->|"persists via"| node_node_db
node_node_auth_lib -->|"reads/writes"| node_node_user_model
node_node_api_login -->|"raises"| node_node_error
node_node_api_register -->|"raises"| node_node_error
node_node_auth_lib -->|"uses"| node_node_utils
node_node_middleware -->|"validates"| node_node_session_lib
node_node_middleware -->|"guards"| node_node_api_login
node_node_middleware -->|"guards"| node_node_api_register
node_node_test_login -->|"covers"| node_node_login_page
node_node_test_login -->|"covers"| node_node_api_login
node_node_test_register -->|"covers"| node_node_register_page
node_node_test_register -->|"covers"| node_node_api_register

click node_node_page "https://github.com/pittu777/health/blob/main/src/app/page.tsx"
click node_node_login_page "https://github.com/pittu777/health/blob/main/src/app/(auth)/login/page.tsx"
click node_node_register_page "https://github.com/pittu777/health/blob/main/src/app/(auth)/register/page.tsx"
click node_node_layout "https://github.com/pittu777/health/blob/main/src/app/layout.tsx"
click node_node_styles "https://github.com/pittu777/health/blob/main/src/app/globals.css"
click node_node_api_login "https://github.com/pittu777/health/blob/main/src/app/api/auth/login/route.ts"
click node_node_api_logout "https://github.com/pittu777/health/blob/main/src/app/api/auth/logout/route.ts"
click node_node_api_refresh "https://github.com/pittu777/health/blob/main/src/app/api/auth/refresh/route.ts"
click node_node_api_register "https://github.com/pittu777/health/blob/main/src/app/api/auth/register/route.ts"
click node_node_auth_form "https://github.com/pittu777/health/blob/main/src/feature/auth/AuthForm.tsx"
click node_node_feature_login "https://github.com/pittu777/health/blob/main/src/feature/auth/Login.tsx"
click node_node_feature_register "https://github.com/pittu777/health/blob/main/src/feature/auth/Register.tsx"
click node_node_logout "https://github.com/pittu777/health/blob/main/src/feature/auth/Logout.tsx"
click node_node_session_refresh "https://github.com/pittu777/health/blob/main/src/feature/auth/SessionRefresh.tsx"
click node_node_use_auth "https://github.com/pittu777/health/blob/main/src/feature/hooks/useAuth.ts"
click node_node_auth_lib "https://github.com/pittu777/health/blob/main/src/lib/auth.ts"
click node_node_session_lib "https://github.com/pittu777/health/blob/main/src/lib/auth/session.ts"
click node_node_db "https://github.com/pittu777/health/blob/main/src/config/db.ts"
click node_node_user_model "https://github.com/pittu777/health/blob/main/src/models/user.model.ts"
click node_node_error "https://github.com/pittu777/health/blob/main/src/lib/AppError.ts"
click node_node_utils "https://github.com/pittu777/health/blob/main/src/lib/utils.ts"
click node_node_middleware "https://github.com/pittu777/health/blob/main/src/middleware/auth.middleware.ts"
click node_node_test_login "https://github.com/pittu777/health/blob/main/tests/auth/login.spec.ts"
click node_node_test_register "https://github.com/pittu777/health/blob/main/tests/auth/register.spec.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_node_page,node_node_login_page,node_node_register_page,node_node_layout,node_node_styles,node_node_api_login,node_node_api_logout,node_node_api_refresh,node_node_api_register toneBlue
class node_node_auth_form,node_node_feature_login,node_node_feature_register,node_node_logout,node_node_session_refresh,node_node_use_auth toneAmber
class node_node_auth_lib,node_node_session_lib,node_node_db,node_node_user_model,node_node_error,node_node_utils,node_node_middleware toneMint
class node_node_test_login,node_node_test_register toneRose
```

## Components

### App Router

Public pages and API route handlers in the Next.js app directory.

- [Home](https://github.com/pittu777/health/blob/main/src/app/page.tsx): route page · Top-level landing page. · `src/app/page.tsx`
- [Login Page](https://github.com/pittu777/health/blob/main/src/app/(auth)/login/page.tsx): route page · Public login screen. · `src/app/(auth)/login/page.tsx`
- [Register Page](https://github.com/pittu777/health/blob/main/src/app/(auth)/register/page.tsx): route page · Public registration screen. · `src/app/(auth)/register/page.tsx`
- [App Shell](https://github.com/pittu777/health/blob/main/src/app/layout.tsx): layout · Global application layout. · `src/app/layout.tsx`
- [Globals](https://github.com/pittu777/health/blob/main/src/app/globals.css): styles · Global CSS for the app. · `src/app/globals.css`
- [Login API](https://github.com/pittu777/health/blob/main/src/app/api/auth/login/route.ts): route handler · Server endpoint for login. · `src/app/api/auth/login/route.ts`
- [Logout API](https://github.com/pittu777/health/blob/main/src/app/api/auth/logout/route.ts): route handler · Server endpoint for logout. · `src/app/api/auth/logout/route.ts`
- [Refresh API](https://github.com/pittu777/health/blob/main/src/app/api/auth/refresh/route.ts): route handler · Server endpoint for session refresh. · `src/app/api/auth/refresh/route.ts`
- [Register API](https://github.com/pittu777/health/blob/main/src/app/api/auth/register/route.ts): route handler · Server endpoint for registration. · `src/app/api/auth/register/route.ts`

### Auth Feature

Reusable auth UI and client-side session behavior.

- [Auth Form](https://github.com/pittu777/health/blob/main/src/feature/auth/AuthForm.tsx): feature component · Shared form scaffolding for auth flows. · `src/feature/auth/AuthForm.tsx`
- [Login UI](https://github.com/pittu777/health/blob/main/src/feature/auth/Login.tsx): feature component · Login workflow component. · `src/feature/auth/Login.tsx`
- [Register UI](https://github.com/pittu777/health/blob/main/src/feature/auth/Register.tsx): feature component · Registration workflow component. · `src/feature/auth/Register.tsx`
- [Logout UI](https://github.com/pittu777/health/blob/main/src/feature/auth/Logout.tsx): feature component · Logout interaction component. · `src/feature/auth/Logout.tsx`
- [Session Refresh](https://github.com/pittu777/health/blob/main/src/feature/auth/SessionRefresh.tsx): client session · Client-side session renewal behavior. · `src/feature/auth/SessionRefresh.tsx`
- [useAuth](https://github.com/pittu777/health/blob/main/src/feature/hooks/useAuth.ts): hook · Client auth state hook. · `src/feature/hooks/useAuth.ts`

### Server Core

Shared auth logic, persistence, middleware, and errors.

- [Auth Core](https://github.com/pittu777/health/blob/main/src/lib/auth.ts): shared auth · Shared auth operations and helpers. · `src/lib/auth.ts`
- [Session Logic](https://github.com/pittu777/health/blob/main/src/lib/auth/session.ts): session helpers · Session lifecycle helpers. · `src/lib/auth/session.ts`
- [DB Config](https://github.com/pittu777/health/blob/main/src/config/db.ts): database config · Database connection/configuration boundary. · `src/config/db.ts`
- [User Model](https://github.com/pittu777/health/blob/main/src/models/user.model.ts): domain model · User entity and persistence model. · `src/models/user.model.ts`
- [App Error](https://github.com/pittu777/health/blob/main/src/lib/AppError.ts): error handling · Application-specific error abstraction. · `src/lib/AppError.ts`
- [Utils](https://github.com/pittu777/health/blob/main/src/lib/utils.ts): shared helpers · Common utility functions. · `src/lib/utils.ts`
- [Auth Middleware](https://github.com/pittu777/health/blob/main/src/middleware/auth.middleware.ts): request guard · Request-level protection and session validation. · `src/middleware/auth.middleware.ts`

### Tests

End-to-end auth flow coverage.

- [Login Spec](https://github.com/pittu777/health/blob/main/tests/auth/login.spec.ts): playwright test · Browser-level login flow test. · `tests/auth/login.spec.ts`
- [Register Spec](https://github.com/pittu777/health/blob/main/tests/auth/register.spec.ts): playwright test · Browser-level registration flow test. · `tests/auth/register.spec.ts`

## Connections

- App Shell → Home: wraps · Application shell frames the landing page.
- App Shell → Login Page: wraps · Application shell frames the login page.
- App Shell → Register Page: wraps · Application shell frames the register page.
- Globals → App Shell: styles · Global CSS supports the shell and pages.
- Login Page → Login UI: renders · Login route page composes the login feature.
- Register Page → Register UI: renders · Register route page composes the register feature.
- Login UI → Auth Form: uses · Login UI shares common auth form structure.
- Register UI → Auth Form: uses · Register UI shares common auth form structure.
- Login UI → Login API: submits to · Login UI posts credentials to the login API.
- Register UI → Register API: submits to · Register UI posts data to the register API.
- Logout UI → Logout API: calls · Logout UI invokes the logout endpoint.
- Session Refresh → Refresh API: refreshes · Client session refresh logic calls the refresh endpoint.
- useAuth → Session Refresh: coordinates · Auth hook coordinates session state and refresh behavior.
- Login API → Auth Core: uses · Login handler relies on shared auth logic.
- Register API → Auth Core: uses · Register handler relies on shared auth logic.
- Logout API → Session Logic: uses · Logout handler uses session lifecycle helpers.
- Refresh API → Session Logic: uses · Refresh handler uses session lifecycle helpers.
- Auth Core → Session Logic: depends on · Core auth logic builds on session helpers.
- Auth Core → DB Config: persists via · Auth logic uses database configuration.
- Auth Core → User Model: reads/writes · Auth logic operates on the user model.
- Login API → App Error: raises · Login failures are expressed through app errors.
- Register API → App Error: raises · Registration failures are expressed through app errors.
- Auth Core → Utils: uses · Shared helpers support auth operations.
- Auth Middleware → Session Logic: validates · Middleware checks session state before protected requests.
- Auth Middleware → Login API: guards · Middleware sits in front of auth-related requests.
- Auth Middleware → Register API: guards · Middleware sits in front of auth-related requests.
- Login Spec → Login Page: covers · Playwright spec exercises the login page.
- Login Spec → Login API: covers · Playwright spec exercises the login endpoint.
- Register Spec → Register Page: covers · Playwright spec exercises the register page.
- Register Spec → Register API: covers · Playwright spec exercises the register endpoint.
