Frontend Structure
This page is a map of the CROForge frontend repo: folders, routes, and where UI vs API client code lives. Frontend here means the Next.js app engineers run locally and deploy—the screens for auth, workspaces, A/B tests, Data Vista, events, and settings—not Smart Code on the customer site.
Doc ID: dev.frontend. Audience: developer.
Words used on this page
| Word | Everyday meaning | Meaning in CROForge |
|---|---|---|
| Frontend | The clickable product UI. | This Next.js codebase: app/, components/, lib/, plus context, hooks, and static/. |
| Next.js | A React framework with file-based pages and a built-in server. | The app framework. Pages live under app/ (App Router). |
| App Router | A filing cabinet: folder names become URL paths. | Next.js routing in app/. Example: app/workspace/[workspaceId]/ab-test → /workspace/{id}/ab-test. |
| Route | A URL the app knows how to show. | Patterns in the table below (auth, workspace shell, A/B, Data Vista, events, config, settings). |
| Component | A reusable piece of UI (a button, a form, a panel). | Feature folders such as components/ab-testing-page/ and shared components/common/condition-rule/. |
| lib | “Library” code that is not a screen: helpers and API callers. | lib/*.ts: services (experimentService, AuthService, …), enums, schemas. |
| Enum | A labeled list of allowed values in code. | lib/enums.ts: experiment statuses, roles, metric types, and related constants. |
| React context | A shared backpack of state that many screens can read without passing props through every layer. | Providers in context/. |
| Hook | A reusable bit of React logic (data fetching, form state). | Shared hooks in hooks/. |
Screenshot filename
Suggested screenshot filename: frontend-structure.png. Capture the app/ folder tree or a route map of the workspace shell. Insert the real image from the WordPress Media Library in place of this note.
Top-level layout
From the frontend/ root, these folders are the ones you will touch most often.
frontend/
├── app/ # Next.js App Router pages
├── components/ # UI + feature components
├── lib/ # API clients, enums, schemas
├── context/ # React context providers
├── hooks/ # Shared hooks
├── static/ # Static assets incl. init.js sample
└── docs/ # This documentation setApp routes (high level)
Square brackets in a path mean a dynamic segment (the real workspace id or experiment id is substituted at runtime).
| Area | Route pattern |
|---|---|
| Auth | /(auth)/login, register, forgot-password, … |
| Invite | /invite |
| Dashboard redirect | /dashboard |
| Workspace shell | /workspace/[workspaceId]/… |
| A/B | .../ab-test, .../ab-test/[experimentId], .../edit |
| Data Vista | .../data-vista/{attributes|segments|metrics} |
| Events | .../events |
| Config | .../configurations/website-app |
| Settings | .../settings/{general|profile|users|installation|…} |
Feature components
| Folder | Purpose |
|---|---|
components/ab-testing-page/ | Pages, variations, traffic, audience, metrics UI |
components/common/condition-rule/ | Shared condition / URL rule builders |
components/modal/ | Create experiment / workspace modals |
components/ui/ | shadcn/Radix primitives |
app/workspace/.../data-vista/*/components/ | Sidebar + detail panels |
Lib services
A service here is a TypeScript module that talks to the backend API. Examples: experimentService, AttributeService, SegmentService, MetricService, EventService, AuthService, WorkspaceService, websiteService.
Enums and statuses: lib/enums.ts.
UI conventions
See ai_instruction.txt at the repo root for dialog/page layout conventions used in this codebase (how modals, pages, and form chrome are expected to look).
Docs taxonomy
When adding features, add or update a page under docs/ and register it in the Documentation taxonomy (stable Doc IDs and paths). That keeps cross-links from rotting when files move.
Related reading
- Architecture
- Local setup
- Documentation taxonomy
