lalitdeveloper215-del/mini-authentication-system

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.