# lalitdeveloper215-del/mini-authentication-system architecture

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

- Interactive diagram: https://gitdiagram.com/lalitdeveloper215-del/mini-authentication-system
- Repository: https://github.com/lalitdeveloper215-del/mini-authentication-system

## Overview

1. **Overall shape**
   - This is a single Next.js 15 App Router application that contains both the UI and the mocked auth backend.
   - There is no separate server service or database; route handlers under `src/app/api/**` act as the backend boundary.

2. **User-facing surfaces**
   - Public pages: `/`, `/login`, `/sso`, and `/unauthorized`.
   - Protected pages: `/dashboard` and `/profile`.
   - The UI is composed from small client components in `src/components` and page-level route components in `src/app/**`.

3. **Auth backend boundary**
   - Authentication logic is centralized in `src/lib/auth/**`.
   - Key responsibilities split there are: mock user identity, token creation/validation, session helpers, and cookie management.
   - This keeps the route handlers thin and makes the auth flow easy to diagram as “UI → API route → auth lib → cookies/session”.

4. **Login and session establishment**
   - `POST /api/auth/login` validates the hardcoded mock credentials from `src/lib/auth/mock-users.ts`.
   - On success it issues an access token and refresh token, then stores both in HTTP-only cookies.
   - The login page (`src/app/login/page.tsx` plus `LoginForm.tsx`) is the entry point for this flow.

5. **Protected request path**
   - Middleware in `src/middleware.ts` is the first protection layer for private routes.
   - It checks whether the request has a valid access token, and if not, it can use the refresh token to mint a new access token automatically.
   - If refresh fails, the user is redirected to `/login` or `/unauthorized` depending on the route.

6. **Token and cookie model**
   - Tokens are not stored in browser JS state or localStorage; they live in HTTP-only cookies for safer handling.
   - `src/lib/auth/cookies.ts` defines cookie behavior, while `tokens.ts` handles token generation/validation concerns.
   - The README indicates a short-lived access token and a longer-lived refresh token, both scoped to the whole app.

7. **Current-user and protected API endpoints**
   - `GET /api/auth/me` returns the authenticated user identity derived from the current token/cookie state.
   - `GET /api/protected` represents a protected backend resource and is useful for showing authenticated API access separate from page navigation.
   - These endpoints demonstrate that the auth layer protects both pages and API calls.

8. **Logout and session teardown**
   - `POST /api/auth/logout` clears the auth cookies and ends the session.
   - The `LogoutButton` component provides the UI action, while the server route performs the actual cookie invalidation.
   - This is a clean example of client intent triggering server-side session removal.

9. **Mock SSO handshake**
   - The SSO flow is intentionally conceptual, not tied to a real identity provider.
   - `GET /api/sso/start` generates a state value and initiates the flow; `GET /api/sso/callback` completes it after validating the state and mock code.
   - Successful SSO also results in auth tokens being issued, which makes SSO land in the same session model as password login.

10. **Frontend auth state display**
   - `AuthStatus`, `TokenDebugPanel`, and `LogoutButton` are support components for showing session state and exercising the flow.
   - The home page and auth pages are mostly orchestration and navigation around those components rather than business logic.

11. **Testing and verification boundary**
   - `tests/auth.spec.ts` contains Playwright end-to-end coverage, which is important because the system’s core behavior spans browser, cookies, middleware, and route handlers.
   - `playwright.config.ts` and the docs in `docs/manual-testing.md` / `docs/project-flow.md` show that the repo treats auth as an integrated flow, not isolated unit logic.

12. **Practical architecture takeaway**
   - The main diagram should show four layers: browser/UI pages, Next.js middleware, API route handlers, and shared auth utilities.
   - External-looking auth behavior is fully mocked inside the app, so the true system boundary is the Next.js process itself, with HTTP-only cookies carrying session state between requests.

Main entry points: [`src/lib/auth/session.ts`](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/lib/auth/session.ts) (Session), [`src/app/api/auth/login/route.ts`](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/api/auth/login/route.ts) (Login API), [`src/lib/auth/tokens.ts`](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/lib/auth/tokens.ts) (Tokens), [`tests/auth.spec.ts`](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/tests/auth.spec.ts) (Auth e2e)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["UI routes"]
  node_src_app_page["Home<br/>page<br/>[page.tsx]"]
  node_src_app_login_page["Login page<br/>[page.tsx]"]
  node_src_app_login_form["Login form<br/>client component<br/>[LoginForm.tsx]"]
  node_src_app_sso_page["SSO page<br/>[page.tsx]"]
  node_src_app_dashboard_page["Dashboard<br/>protected page<br/>[page.tsx]"]
  node_src_app_profile_page["Profile<br/>protected page<br/>[page.tsx]"]
  node_src_app_unauthorized_page["Unauthorized<br/>page<br/>[page.tsx]"]
  node_src_components_authstatus["Auth status<br/>client component<br/>[AuthStatus.tsx]"]
  node_src_components_tokendebugpanel["Token debug<br/>client component"]
  node_src_components_logoutbutton["Logout button<br/>client component<br/>[LogoutButton.tsx]"]
end

subgraph group_api["API routes"]
  node_src_app_api_auth_login_route["Login API<br/>route handler<br/>[route.ts]"]
  node_src_app_api_auth_logout_route["Logout API<br/>route handler<br/>[route.ts]"]
  node_src_app_api_auth_me_route["Me API<br/>route handler<br/>[route.ts]"]
  node_src_app_api_auth_refresh_route["Refresh API<br/>route handler<br/>[route.ts]"]
  node_src_app_api_protected_route["Protected API<br/>route handler<br/>[route.ts]"]
  node_src_app_api_sso_start_route["SSO start<br/>route handler<br/>[route.ts]"]
  node_src_app_api_sso_callback_route["SSO callback<br/>route handler<br/>[route.ts]"]
end

subgraph group_auth["Auth core"]
  node_src_lib_auth_mock_users[("Mock users<br/>identity store<br/>[mock-users.ts]")]
  node_src_lib_auth_tokens{{"Tokens<br/>token service<br/>[tokens.ts]"}}
  node_src_lib_auth_cookies{{"Cookies<br/>cookie helper<br/>[cookies.ts]"}}
  node_src_lib_auth_session{{"Session<br/>[session.ts]"}}
  node_src_lib_auth_types["Auth types<br/>[types.ts]"]
end

subgraph group_infra["Infra"]
  node_src_middleware{{"Middleware<br/>auth gate<br/>[middleware.ts]"}}
  node_src_lib_api_response["Response helper<br/>[api-response.ts]"]
  node_tests_auth_spec["Auth e2e<br/>playwright test<br/>[auth.spec.ts]"]
end

node_src_app_page -->|"shows session"| node_src_components_authstatus
node_src_app_page -->|"shows tokens"| node_src_components_tokendebugpanel
node_src_app_page -->|"offers logout"| node_src_components_logoutbutton
node_src_app_login_page -->|"hosts form"| node_src_app_login_form
node_src_app_login_form -->|"POST credentials"| node_src_app_api_auth_login_route
node_src_app_sso_page -->|"start SSO"| node_src_app_api_sso_start_route
node_src_components_logoutbutton -->|"POST logout"| node_src_app_api_auth_logout_route
node_src_app_dashboard_page -->|"protected by"| node_src_middleware
node_src_app_profile_page -->|"protected by"| node_src_middleware
node_src_middleware -->|"validates token"| node_src_lib_auth_tokens
node_src_middleware -->|"refreshes via"| node_src_app_api_auth_refresh_route
node_src_app_api_auth_login_route -->|"checks creds"| node_src_lib_auth_mock_users
node_src_app_api_auth_login_route -->|"issues tokens"| node_src_lib_auth_tokens
node_src_app_api_auth_login_route -->|"sets cookies"| node_src_lib_auth_cookies
node_src_app_api_auth_login_route -->|"builds session"| node_src_lib_auth_session
node_src_app_api_auth_logout_route -->|"clears cookies"| node_src_lib_auth_cookies
node_src_app_api_auth_me_route -->|"reads session"| node_src_lib_auth_session
node_src_app_api_protected_route -->|"guards resource"| node_src_lib_auth_session
node_src_app_api_auth_refresh_route -->|"renews token"| node_src_lib_auth_tokens
node_src_app_api_auth_refresh_route -->|"updates cookies"| node_src_lib_auth_cookies
node_src_app_api_sso_start_route -->|"creates state"| node_src_lib_auth_session
node_src_app_api_sso_callback_route -->|"verifies callback"| node_src_lib_auth_session
node_src_app_api_sso_callback_route -->|"issues tokens"| node_src_lib_auth_tokens
node_src_app_api_sso_callback_route -->|"sets cookies"| node_src_lib_auth_cookies
node_src_lib_auth_session -->|"uses tokens"| node_src_lib_auth_tokens
node_src_lib_auth_session -->|"uses cookies"| node_src_lib_auth_cookies
node_src_lib_auth_tokens -->|"shares shapes"| node_src_lib_auth_types
node_src_lib_auth_session -->|"shares shapes"| node_src_lib_auth_types
node_tests_auth_spec -.->|"verifies"| node_src_middleware
node_tests_auth_spec -.->|"verifies"| node_src_app_api_auth_login_route
node_tests_auth_spec -.->|"verifies"| node_src_app_api_sso_callback_route
node_tests_auth_spec -.->|"verifies"| node_src_app_api_auth_logout_route
node_tests_auth_spec -.->|"verifies"| node_src_app_api_auth_me_route

click node_src_app_page "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/page.tsx"
click node_src_app_login_page "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/login/page.tsx"
click node_src_app_login_form "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/login/LoginForm.tsx"
click node_src_app_sso_page "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/sso/page.tsx"
click node_src_app_dashboard_page "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/dashboard/page.tsx"
click node_src_app_profile_page "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/profile/page.tsx"
click node_src_app_unauthorized_page "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/unauthorized/page.tsx"
click node_src_components_authstatus "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/components/AuthStatus.tsx"
click node_src_components_tokendebugpanel "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/components/TokenDebugPanel.tsx"
click node_src_components_logoutbutton "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/components/LogoutButton.tsx"
click node_src_app_api_auth_login_route "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/api/auth/login/route.ts"
click node_src_app_api_auth_logout_route "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/api/auth/logout/route.ts"
click node_src_app_api_auth_me_route "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/api/auth/me/route.ts"
click node_src_app_api_auth_refresh_route "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/api/auth/refresh/route.ts"
click node_src_app_api_protected_route "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/api/protected/route.ts"
click node_src_app_api_sso_start_route "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/api/sso/start/route.ts"
click node_src_app_api_sso_callback_route "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/api/sso/callback/route.ts"
click node_src_middleware "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/middleware.ts"
click node_src_lib_auth_mock_users "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/lib/auth/mock-users.ts"
click node_src_lib_auth_tokens "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/lib/auth/tokens.ts"
click node_src_lib_auth_cookies "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/lib/auth/cookies.ts"
click node_src_lib_auth_session "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/lib/auth/session.ts"
click node_src_lib_auth_types "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/lib/auth/types.ts"
click node_src_lib_api_response "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/lib/api-response.ts"
click node_tests_auth_spec "https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/tests/auth.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_src_app_page,node_src_app_login_page,node_src_app_login_form,node_src_app_sso_page,node_src_app_dashboard_page,node_src_app_profile_page,node_src_app_unauthorized_page,node_src_components_authstatus,node_src_components_tokendebugpanel,node_src_components_logoutbutton toneBlue
class node_src_app_api_auth_login_route,node_src_app_api_auth_logout_route,node_src_app_api_auth_me_route,node_src_app_api_auth_refresh_route,node_src_app_api_protected_route,node_src_app_api_sso_start_route,node_src_app_api_sso_callback_route toneAmber
class node_src_lib_auth_mock_users,node_src_lib_auth_tokens,node_src_lib_auth_cookies,node_src_lib_auth_session,node_src_lib_auth_types toneMint
class node_src_middleware,node_src_lib_api_response,node_tests_auth_spec toneRose
```

## Components

### UI routes

Next.js pages and client-side auth controls

- [Home](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/page.tsx): page · Public landing page and orchestration shell · `src/app/page.tsx`
- [Login page](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/login/page.tsx): page · Public login surface · `src/app/login/page.tsx`
- [Login form](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/login/LoginForm.tsx): client component · Submits credentials and starts password login · `src/app/login/LoginForm.tsx`
- [SSO page](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/sso/page.tsx): page · Public SSO entry surface · `src/app/sso/page.tsx`
- [Dashboard](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/dashboard/page.tsx): protected page · Authenticated app area · `src/app/dashboard/page.tsx`
- [Profile](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/profile/page.tsx): protected page · Authenticated user profile area · `src/app/profile/page.tsx`
- [Unauthorized](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/unauthorized/page.tsx): page · Fallback when access is denied · `src/app/unauthorized/page.tsx`
- [Auth status](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/components/AuthStatus.tsx): client component · Displays current session and user state · `src/components/AuthStatus.tsx`
- [Token debug](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/components/TokenDebugPanel.tsx): client component · Shows token/session diagnostics · `src/components/TokenDebugPanel.tsx`
- [Logout button](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/components/LogoutButton.tsx): client component · Triggers session teardown · `src/components/LogoutButton.tsx`

### API routes

Route handlers for auth and protected backend access

- [Login API](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/api/auth/login/route.ts): route handler · Validates credentials and issues tokens · `src/app/api/auth/login/route.ts`
- [Logout API](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/api/auth/logout/route.ts): route handler · Clears auth cookies and ends the session · `src/app/api/auth/logout/route.ts`
- [Me API](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/api/auth/me/route.ts): route handler · Returns the current authenticated user · `src/app/api/auth/me/route.ts`
- [Refresh API](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/api/auth/refresh/route.ts): route handler · Mints a new access token from refresh state · `src/app/api/auth/refresh/route.ts`
- [Protected API](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/api/protected/route.ts): route handler · Authenticated backend resource · `src/app/api/protected/route.ts`
- [SSO start](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/api/sso/start/route.ts): route handler · Begins mock SSO with state generation · `src/app/api/sso/start/route.ts`
- [SSO callback](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/app/api/sso/callback/route.ts): route handler · Completes mock SSO and issues tokens · `src/app/api/sso/callback/route.ts`

### Auth core

Shared token, session, cookie, and mock identity logic

- [Mock users](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/lib/auth/mock-users.ts): identity store · Hardcoded credentials and user identities · `src/lib/auth/mock-users.ts`
- [Tokens](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/lib/auth/tokens.ts): token service · Creates and validates access and refresh tokens · `src/lib/auth/tokens.ts`
- [Cookies](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/lib/auth/cookies.ts): cookie helper · Defines HTTP-only auth cookie behavior · `src/lib/auth/cookies.ts`
- [Session](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/lib/auth/session.ts): session helper · Builds and reads authenticated session state · `src/lib/auth/session.ts`
- [Auth types](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/lib/auth/types.ts): types · Shared auth and session shapes · `src/lib/auth/types.ts`

### Infra

Middleware, response helpers, and testing harness

- [Middleware](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/middleware.ts): auth gate · Protects private routes and refreshes access tokens · `src/middleware.ts`
- [Response helper](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/src/lib/api-response.ts): utility · Shared API response formatting · `src/lib/api-response.ts`
- [Auth e2e](https://github.com/lalitdeveloper215-del/mini-authentication-system/blob/main/tests/auth.spec.ts): playwright test · End-to-end coverage for browser, cookies, middleware, and routes · `tests/auth.spec.ts`

## Connections

- Home → Auth status: shows session · Home page presents auth state
- Home → Token debug: shows tokens · Home page exposes token diagnostics
- Home → Logout button: offers logout · Home page can trigger session teardown
- Login page → Login form: hosts form · Login page wraps the credential entry component
- Login form → Login API: POST credentials · Client submits login request
- SSO page → SSO start: start SSO · Entry page initiates the mock SSO flow
- Logout button → Logout API: POST logout · Client requests session removal
- Dashboard → Middleware: protected by · Private page access is mediated by middleware
- Profile → Middleware: protected by · Private page access is mediated by middleware
- Middleware → Tokens: validates token · Checks access token and refreshes if needed
- Middleware → Refresh API: refreshes via · Can mint a new access token when expired
- Login API → Mock users: checks creds · Login route validates the hardcoded user store
- Login API → Tokens: issues tokens · Successful login creates access and refresh tokens
- Login API → Cookies: sets cookies · Tokens are stored in HTTP-only cookies
- Login API → Session: builds session · Login establishes authenticated session state
- Logout API → Cookies: clears cookies · Logout invalidates auth cookies
- Me API → Session: reads session · Me endpoint derives identity from current auth state
- Protected API → Session: guards resource · Protected API requires authenticated session state
- Refresh API → Tokens: renews token · Refresh endpoint issues a new access token
- Refresh API → Cookies: updates cookies · Refresh response persists new auth cookies
- SSO start → Session: creates state · SSO start prepares temporary handshake state
- SSO callback → Session: verifies callback · Callback validates state and mock code
- SSO callback → Tokens: issues tokens · Successful SSO lands in the same session model
- SSO callback → Cookies: sets cookies · SSO completion writes auth cookies
- Session → Tokens: uses tokens · Session helper depends on token claims and expiry
- Session → Cookies: uses cookies · Session helper reads and writes cookie state
- Tokens → Auth types: shares shapes · Token logic uses shared auth types
- Session → Auth types: shares shapes · Session logic uses shared auth types
- Auth e2e → Middleware: verifies · E2E tests cover protection and refresh behavior
- Auth e2e → Login API: verifies · E2E tests cover login flow
- Auth e2e → SSO callback: verifies · E2E tests cover the SSO completion path
- Auth e2e → Logout API: verifies · E2E tests cover logout and cookie clearing
- Auth e2e → Me API: verifies · E2E tests cover authenticated identity lookup