(app)

Next.js 16 App Router entry point providing routing, layouts, pages, server actions, and API endpoints.

App Directory (`app/`)

Next.js 16 App Router entry point providing routing, layouts, pages, server actions, and API endpoints.

Purpose

Defines the user-facing application structure using the Next.js App Router:

File-based routing (folders become URL paths)
Server and client component orchestration
Server actions for form handling
API routes for REST endpoints
Layouts for shared UI structure

Structure

The app directory is organized by feature and route:

app/
├── layout.tsx              # Root layout (theme, nav, header, footer)
├── page.tsx                # Home page (/)
├── actions/                # Server actions (geocoding, bulk processing)
├── api/                    # API routes (system status, testing endpoints)
├── lookup/                 # Single address lookup page (/lookup)
├── bulk/                   # Bulk address processing page (/bulk)
├── test-api/               # API testing interface (/test-api)
└── system-status/          # System health monitoring (/system-status)

Next.js App Router Concepts

File Conventions

layout.tsx: Shared UI wrapper for route segments
page.tsx: Unique page content for a route
route.ts: API endpoints (GET, POST, etc.)
loading.tsx: Loading UI during data fetching
error.tsx: Error boundary for route segment

Server vs Client Components

Server Components (default): Render on server, can directly access backend resources
Client Components ("use client"): Interactive UI with hooks, event handlers, browser APIs

Server Actions

Functions marked with "use server" that run on the server but can be called from client components:

Type-safe client-to-server communication
Form handling with progressive enhancement
No manual API route setup required

Routes

The application provides these user-facing pages:

/ - Landing page with feature overview
/lookup - Single address lookup with autocomplete
/bulk - Bulk address processing (up to 1,000 addresses)
/test-api - API testing interface for developers
/system-status - Real-time health monitoring dashboard

API Endpoints

REST endpoints for programmatic access:

GET /api/system-status - Health check and cache statistics
GET /api/system-status?checkApis=true - Deep health check with external API verification

Architecture Integration

The app layer sits at the top of the clean architecture:

App Router (Presentation)
    ↓ calls
Server Actions / Pages
    ↓ executes
Domain Use Cases
    ↓ depends on
Ports (interfaces)
    ↑ implemented by
Adapters (NJ API, Cache, HTTP)

Key Features

SSR/SSG: Server-side rendering and static generation for performance
Streaming: Progressive page rendering with React Server Components
Parallel Routes: Simultaneous page segments with independent loading states
Intercepting Routes: Modal-like overlays without page navigation
Route Groups: Organize routes without affecting URL structure
Metadata API: SEO-friendly page metadata and Open Graph tags

Development

Creating New Routes

Create a folder in app/ matching the desired URL path
Add page.tsx for the page content
Optionally add layout.tsx for shared UI
Add loading.tsx for loading states
Add error.tsx for error boundaries

Adding Server Actions

Create action file in app/actions/ with "use server" directive
Export async functions that return serializable data
Import and call from client components with useTransition or form actions

Creating API Routes

Create route.ts in desired path (e.g., app/api/foo/route.ts → /api/foo)
Export HTTP method handlers: GET, POST, PUT, DELETE, etc.
Return NextResponse.json() with typed data

Testing

E2E Tests: Playwright tests in src/__tests__/e2e/ navigate actual routes
Integration Tests: Server action tests verify form handling
Unit Tests: Page component tests with React Testing Library

actions/ - Server actions for form handling
api/ - API route handlers
Domain Use Cases - Business logic called by actions
Components - React components used in pages