How amalkrishnaas/auth-toolbox works
1. Overall shape
- This is a Next.js 14 App Router authentication starter.
- The architecture is centered around a server-first auth stack: Auth.js/NextAuth v5, Prisma/PostgreSQL, server actions, and route protection via middleware.
2. Route structure: public vs protected
- Public pages live under app/auth/* for sign-in, registration, reset, new password, and verification flows.
- Protected application pages live under app/(protected)/* and are grouped into client, server, admin, and settings.
- app/layout.tsx and app/(protected)/layout.tsx provide the global and authenticated shells, with shared navigation in app/(protected)/_components/Navbar.tsx.
3. Authentication entry points
- The central auth runtime is split across auth.ts and auth.config.ts.
- app/api/auth/[...nextauth]/route.ts exposes the Auth.js handler for sign-in, session, and provider callbacks.
- app/api/admin/route.ts is a separate protected API boundary for admin-only behavior.
4. Server actions as the main mutation layer
- The actions/ folder contains server actions for login, register, logout, settings updates, password reset, new password submission, admin operations, and verification flows.
- These actions are the primary bridge between form UI and backend state changes, keeping most auth mutations off the client.
5. Data access and persistence
- Prisma is the ORM layer, with schema and migrations under prisma/.
- The data/ folder contains model-specific access helpers for users, accounts, tokens, password reset tokens, verification tokens, and two-factor data.
- lib/db.ts likely provides the shared Prisma client, and lib/tokens.ts centralizes token generation/verification logic.
6. Auth flow features
- The repo supports email/password auth, OAuth providers, email verification, password reset, and two-factor authentication.
- These flows are coordinated through the server actions, the token tables, and the auth pages under app/auth/*.
- app/auth/error/page.tsx and app/auth/new-verification/page.tsx handle post-flow states and failure recovery.
7. Session and identity propagation
- The hooks in hooks/ expose the current user and role to client components.
- next-auth.d.ts extends session/user typing so the app can safely consume role and auth metadata.
- components/auth/RoleGate.tsx and components/UserInfo.tsx are presentation gates around identity-aware UI.
8. Protected UI composition
- The protected area is split by audience or capability: client, server, and admin pages.
- This suggests a layered authorization model where some pages are merely authenticated, while others check role or admin claims.
- components/auth/UserButton.tsx, LogoutButton.tsx, and LoginButton.tsx provide the session-aware navigation actions.
9. Email and verification delivery
- mail.ts and email-template.ts encapsulate outbound email delivery, backed by Resend per the README.
- Verification and reset flows depend on these email paths, so mail is a first-class subsystem rather than incidental utility.
- The token tables in data/ support one-time links and time-bound verification.
10. Cross-cutting security controls
- middleware.ts is the route-level guard that enforces access control before pages render.
- middleware/ratelimit.ts adds abuse protection, likely around sensitive auth endpoints or actions.
- routes.ts appears to centralize route constants so auth redirects and guards stay consistent.
11. UI and form system
- components/auth/* contains the reusable auth-specific forms and wrappers, while components/ui/* is the lower-level design system built on shadcn/ui.
- Validation and form state are handled in the form components, with components/FormError.tsx and components/FormSuccess.tsx providing common feedback states.
- components/settings/settings-form.tsx is the main authenticated profile/settings editor.
12. Architecture boundaries to draw
- Client components: forms, buttons, gates, and user-facing shells.
- Server actions and route handlers: all mutations and auth endpoints.
- Persistence: Prisma models plus token/user/account tables.
- External services: OAuth providers, Resend for email, PostgreSQL via Neon.
- Security layer: Auth.js session handling plus middleware and rate limiting.
13. What is intentionally not central
- This is not a generic business app; the entire repository is optimized around identity lifecycle management.
- Most “application” pages are placeholders for auth-state-based access patterns, demonstrating how to separate public, authenticated, and admin experiences within one Next.js codebase.
Main entry points: actions Server actions · auth.ts Auth core · layout.tsx Protected shell · middleware.ts Middleware
Components 22
Routes
Public and protected Next.js App Router surfaces.
- App shell · Global application layout for the App Router.
app/layout.tsx - Protected shell · Authenticated app shell with shared navigation.
app/(protected)/layout.tsx - Auth pages · Sign-in, registration, reset, and verification pages.
app/auth - Protected pages · Client, server, admin, and settings sections.
app/(protected)
Auth Runtime
Core authentication configuration and handlers.
- Auth handler · Auth.js endpoint for sign-in, session, and callbacks.
app/api/auth/[...nextauth]/route.ts - Admin API · Protected API boundary for admin-only behavior.
app/api/admin/route.ts - Auth config · Provider, callback, and session configuration.
auth.config.ts - Auth core · Server auth composition and shared auth entrypoint.
auth.ts
Mutations
Server actions that drive auth and account changes.
- Server actions · Login, register, logout, settings, reset, verification, and admin actions.
actions
Persistence
Prisma models and shared data access helpers.
- User data · User and account persistence helpers.
data/user.ts - Token data · Password reset, verification, and two-factor token storage.
data/verification-token.ts - 2FA data · Two-factor token and confirmation persistence helpers.
data/two-factor-token.ts
UI
Reusable auth, settings, and shell components.
- Auth UI · Auth forms, buttons, role gates, and shared feedback components.
components/auth - Settings UI · Authenticated profile and settings editor.
components/settings/settings-form.tsx - Shared UI · User info and reusable success/error messaging.
components - Navbar · Authenticated navigation and session-aware actions.
app/(protected)/_components/Navbar.tsx
Security
Route protection, rate limiting, and session typing.
- Middleware · Edge-level access control for protected routes.
middleware.ts - Rate limit · Rate limiting for sensitive auth endpoints and actions.
middleware/ratelimit.ts - Session types · Extends auth session and user typing with role metadata.
next-auth.d.ts
Services
Email, tokens, and database integration.
- DB client · Shared Prisma database connection.
lib/db.ts - Token service · Token generation and verification helpers.
lib/tokens.ts - Mail service · Outbound email composition and sending.
mail.ts
Connections 28
- App shell → Auth pages: renders · Global layout wraps public auth screens.
- App shell → Protected shell: includes · Application shell nests protected shell.
- Protected shell → Navbar: uses · Protected layout shares the navigation bar.
- Protected shell → Protected pages: hosts · Authenticated layout contains protected sections.
- Auth pages → Auth UI: uses · Public auth screens compose reusable auth forms.
- Protected pages → Settings UI: uses · Settings section uses the profile editor.
- Protected pages → Shared UI: uses · Protected pages display shared user/feedback UI.
- Auth UI → Server actions: submits to · Forms and buttons trigger mutation actions.
- Settings UI → Server actions: updates via · Settings changes are persisted through server actions.
- Server actions → User data: reads/writes · Account flows access user and account records.
- Server actions → Token data: uses · Reset and verification flows store one-time tokens.
- Server actions → 2FA data: uses · Two-factor flows persist confirmations and tokens.
- Server actions → Mail service: sends · Verification and reset flows deliver email.
- Server actions → Token service: issues · Actions create and validate flow tokens.
- User data → DB client: backed by · User persistence runs through Prisma.
- Token data → DB client: backed by · Token tables are accessed through Prisma.
- 2FA data → DB client: backed by · Two-factor persistence uses Prisma models.
- Auth core → Auth config: configured by · Auth core is assembled from the shared config.
- Auth handler → Auth core: serves · Route handler exposes the auth runtime.
- Admin API → Server actions: delegates · Admin API boundary is implemented through actions.
- Middleware → Auth core: protects · Middleware relies on auth state for route guarding.
- Middleware → Protected shell: guards · Protected app surface is gated before render.
- Middleware → Rate limit: invokes · Security middleware can rate limit sensitive requests.
- Auth core → Session types: extends · Session and user claims are typed for app consumption.
- Shared UI → Session types: consumes · Identity-aware UI depends on typed session data.
- Navbar → Auth core: reads session · Navigation changes based on current auth state.
- Mail service → Token service: encodes links · Email content embeds time-bound auth tokens.
- Auth config → User data: uses adapters · Auth configuration maps identity records to persistence.