App Service (Next.js)

wordloop-app is the frontend UI. Deployed on the Next.js 16 App Router, the application prioritizes React Server Components (RSC) to construct HTML payloads instantly on initial load, only falling back to Client Components for pure user interactivity.

Architecture & Layout

[!IMPORTANT]
The project enforces an absolute inward-facing dependency graph. Application routing logic can depend on internal business functions hooks, but business core functions must never depend on UI primitives.

services/wordloop-app/
├── app/                  # Next.js App Router (Pages, Layouts, API Proxies)
├── components/           # UI Elements
│   ├── ui/               # Shadcn/Radix Primitives
│   └── <domain>/         # Feature-specific components
├── hooks/                # SWR hooks for client caching
├── lib/                  # Core Logic (NO UI DEPENDENCIES ALLOWED)
│   ├── schemas/          # Zod schema definitions
│   ├── api.ts            # Generated HTTP client
│   └── utils.ts          # Pure logic and Tailwind mergers
├── orval.config.ts       # Code generation rules
└── globals.css           # Tailwind v4 configuration

Local Development Workflow

1. Start System Infrastructure

   ./dev start infra core ml

   (Boots databases, memory layer, and all backing backend services)

2. Start Next.js

   cd services/wordloop-app
   pnpm run dev

   Visit http://localhost:4001 in your browser.

Development Guidelines

• Tailwind v4 First: Token declaration is strictly CSS-first. Please review our Design Guide for UI patterns.
• Strict Boundary Checks: Always review the rigid Frontend Architecture Rules before abstracting components or lifting state.