Owner: Engineering Team | Last Updated: 2026-01-30 | Status: Current
The WWAI Web App follows the Next.js App Router convention with a well-organized directory structure. This document explains every top-level directory and sub-directory, the purpose of each, naming conventions, and guidance on where to place new files. For the full web app overview, see Web App Overview.
app-main/
├── .github/
│ └── workflows/ # GitHub Actions CI/CD pipelines
│ ├── dev.yml # Development deployment
│ ├── preprod.yml # Preproduction deployment
│ └── prod.yml # Production deployment
│
├── app/ # Next.js App Router (all routes)
│ ├── api/ # Server-side API routes
│ │ ├── auth/ # NextAuth.js API route ([...nextauth])
│ │ ├── churnkey/ # Churnkey integration endpoint
│ │ └── ipconfig/ # IP configuration/detection endpoint
│ │
│ └── [locale]/ # Locale-segmented routes (dynamic: en, de, es, etc.)
│ ├── (dashboard)/ # Route group: authenticated dashboard pages
│ │ ├── dashboard/ # Main dashboard page
│ │ ├── documents/ # Document management page
│ │ ├── settings/ # User settings page
│ │ ├── refer-a-friend/ # Referral program page
│ │ └── request-a-feature/ # Feature request page
│ │
│ ├── humanizer/ # Humanizer tool page
│ ├── detector/ # AI detector tool page
│ │
│ ├── login/ # Login page
│ ├── register/ # Registration page
│ ├── checkout/ # Checkout/payment page
│ ├── account-setup/ # Post-registration account setup
│ ├── reset-password/ # Password reset page
│ ├── forgot-password/ # Forgot password page
│ ├── verify/ # Email verification page
│ │
│ ├── embed-*/ # Embed widget variants (multiple)
│ │
│ ├── layout.tsx # Root locale layout
│ └── page.tsx # Locale landing page
│
├── components/ # Shared React components
│ ├── partials/ # Page-specific component sections
│ │ ├── humanizer/ # Humanizer page components
│ │ │ ├── Humanizer.tsx # Main humanizer component (951 lines)
│ │ │ ├── HumanizerLayout.tsx # Layout wrapper
│ │ │ ├── HumanizerContext.tsx # Context provider
│ │ │ ├── HumanizerSelect.tsx # Configuration selectors
│ │ │ ├── HumanizerBanner.tsx # Feature banner
│ │ │ ├── DetectorResult.tsx # Inline detector results
│ │ │ └── DetectorScorecard.tsx # Score visualization
│ │ ├── detector/ # Detector page components
│ │ │ ├── DetectorLayout.tsx # Layout wrapper
│ │ │ ├── DetectorResult.tsx # Detection results display
│ │ │ └── DetectorUserData.tsx # User data panel
│ │ ├── dashboard/ # Dashboard page components
│ │ ├── settings/ # Settings page components
│ │ └── nav-bar/ # Navigation bar components
│ │
│ ├── elements/ # Reusable UI elements (cross-page)
│ │ └── Checkout.tsx # Stripe checkout element
│ │
│ ├── ui/ # UI primitives (buttons, inputs, modals, etc.)
│ │
│ ├── hooks/ # Component-scoped custom hooks
│ │
│ └── GTM/ # Google Tag Manager integration components
│
├── server/ # Server-only code
│ └── auth.ts # NextAuth.js configuration (providers, callbacks, JWT)
│
├── lib/ # Library code (shared utilities)
│ └── store/ # Redux store
│ ├── store.ts # Store configuration (configureStore)
│ ├── userSlice.ts # User state slice
│ ├── documentsSlice.ts # Documents state slice
│ ├── humanizerSelectionSlice.ts # Humanizer config slice
│ ├── commonSlice.ts # Shared/common state slice
│ └── pauseSlice.ts # Pause flow modals state slice
│
├── hooks/ # App-level custom hooks
│ ├── useWordsUsage.ts # Word usage tracking
│ ├── useDocumentActions.ts # Document CRUD hook
│ ├── use-countdown.ts # Countdown timer hook
│ └── use-on-click-outside.ts # Click outside detection
│
├── utils/ # Utility functions
│ ├── api.ts # Axios instance & configuration
│ ├── validation.ts # Form validation schemas (Yup)
│ ├── sanitize.ts # HTML/text sanitization
│ ├── countWords.ts # Word counting utility
│ └── ... # Other utility functions
│
├── config/ # Application configuration
│ ├── site.ts # Site config (navigation, routes, metadata)
│ └── fonts.ts # Font configuration
│
├── data/ # Static data definitions
│ ├── plan.tsx # Pricing plans and features
│ ├── publicDetectors.ts # Supported detector engines list
│ └── socials.tsx # Social media links
│
├── types/ # TypeScript type definitions
│ └── *.ts # Shared interfaces and types
│
├── messages/ # i18n translation files
│ ├── en.json # English
│ ├── de.json # German
│ ├── es.json # Spanish
│ ├── fr.json # French
│ ├── it.json # Italian
│ ├── pt.json # Portuguese
│ ├── zh.json # Chinese
│ └── nl.json # Dutch
│
├── i18n/ # i18n configuration
│ ├── request.ts # next-intl request configuration
│ └── routing.ts # Locale routing configuration
│
├── public/ # Static assets (images, icons, fonts)
│
├── middleware.ts # Next.js middleware (locale detection, redirects)
├── next.config.ts # Next.js configuration
├── tailwind.config.js # Tailwind CSS configuration
├── tsconfig.json # TypeScript configuration
├── package.json # Dependencies and scripts
├── Dockerfile # Docker build configuration
└── .env.local # Local environment variables (not committed)
app/ -- Routes & PagesThe App Router directory. Every folder here maps to a URL route. Key conventions:
[locale]/: Dynamic segment for i18n. All user-facing routes are nested here.(dashboard)/: Route group (parentheses = no URL segment). Groups authenticated pages under a shared layout.api/: Server-side API routes. These run on the Node.js server, not in the browser.Each page folder typically contains:
page.tsx -- The page component (required by Next.js)layout.tsx -- Optional layout wrapperloading.tsx -- Optional loading stateerror.tsx -- Optional error boundarycomponents/ -- React ComponentsSplit into four categories:
| Subfolder | Purpose | Example |
|---|---|---|
partials/ |
Page-specific sections. Organized by feature. | partials/humanizer/Humanizer.tsx |
elements/ |
Reusable cross-page components | elements/Checkout.tsx |
ui/ |
Primitive UI components (design system) | Buttons, inputs, modals |
hooks/ |
Component-scoped hooks | - |
GTM/ |
Analytics tracking components | GTM script injection |
lib/store/ -- Redux StoreAll Redux-related code lives here. Each slice file defines state shape, reducers, and async thunks.
hooks/ -- App-Level HooksCustom React hooks used across multiple pages. Distinguished from components/hooks/ which are component-scoped.
utils/ -- UtilitiesPure functions and configuration. No React code. Key file: api.ts which configures the Axios HTTP client.
config/ -- ConfigurationApp-wide configuration including navigation structure (site.ts) and font loading (fonts.ts).
data/ -- Static DataHardcoded data used in the UI (pricing plans, detector lists, social links). These are not fetched from the API at runtime.
types/ -- TypeScript TypesShared interfaces and type definitions. Keep types here when used across multiple files.
messages/ -- TranslationsJSON files for each supported locale. Keys are organized by feature/page.
i18n/ -- i18n ConfigConfiguration for next-intl: locale routing rules and request-time locale detection.
| Convention | Example | Used For |
|---|---|---|
| PascalCase | Humanizer.tsx, DetectorResult.tsx |
React components |
| camelCase | userSlice.ts, countWords.ts |
Utilities, hooks, slices |
| kebab-case | use-countdown.ts, use-on-click-outside.ts |
Some hooks (legacy pattern) |
| lowercase | api.ts, validation.ts, sanitize.ts |
Utility modules |
| kebab-case directories | nav-bar/, refer-a-friend/ |
Route segments, component folders |
A typical component file follows this pattern:
"use client"; // If client-side interactivity is needed
import React from "react";
// External imports
// Internal imports (components, hooks, utils, types)
interface ComponentProps {
// Props definition
}
export default function Component({ ...props }: ComponentProps) {
// Hooks
// State
// Effects
// Handlers
// Render
return <div>...</div>;
}
app/[locale]/your-new-page/
└── page.tsx
app/[locale]/(dashboard)/your-new-page/.app/[locale]/.Page-specific component (used only on one page):
components/partials/your-feature/YourComponent.tsx
Reusable component (used across multiple pages):
components/elements/YourComponent.tsx
UI primitive (design system level):
components/ui/YourPrimitive.tsx
lib/store/yourNewSlice.ts
Then register it in lib/store/store.ts:
import yourNewReducer from "./yourNewSlice";
export const store = configureStore({
reducer: {
// ...existing slices
yourNew: yourNewReducer,
},
});
App-level hook (used across pages):
hooks/useYourHook.ts
Component-level hook (used within a component tree):
components/hooks/useYourHook.ts
utils/yourUtility.ts
types/yourType.ts
app/api/your-endpoint/route.ts
Add the key to all 8 message files:
messages/en.json
messages/de.json
messages/es.json
messages/fr.json
messages/it.json
messages/pt.json
messages/zh.json
messages/nl.json
| Date | Author | Change |
|---|---|---|
| 2026-01-30 | Admin | Initial creation |
Prev: Local Development Setup | Next: Web App - Routing | Up: WalterWrites