Architecture
This page is the developer map of CROForge: which piece of software talks to which, what each piece is responsible for, and where the important files live. In everyday language, architecture means “how the house is built”—rooms, wiring, and who lives where. In CROForge it means the three-part system: the web app your team uses (frontend), the server that stores data and serves Smart Code (backend), and the JavaScript that runs on a customer’s website (Smart Code).
Doc ID: dev.architecture. Audience: developer.
Words used on this page
| Word | Everyday meaning | Meaning in CROForge |
|---|---|---|
| Architecture | The blueprint of a system: parts and how they connect. | Frontend app + backend API + Smart Code on the customer site, talking over HTTPS. |
| Frontend | The screens people click—forms, lists, buttons. | The Next.js app in this repo: login, workspaces, experiment CRUD, Data Vista, settings, Monaco editor. |
| Backend | The “office in the back” that stores records and answers requests. | API + persistence + auth + compile/serve Smart Code per workspace + ingest events. |
| API | A waiter: you ask for something, it brings data back in a standard way. | HTTPS endpoints the frontend calls, and the beacon URLs Smart Code posts events to. |
| HTTPS | Encrypted web traffic (the lock in the browser). | How the frontend talks to the backend, and how sites load init.js. |
| Smart Code | A small script pasted on a website. | Workspace init.js: targeting, assignment, CSS/JS apply, event capture, integrations. Reference bundle: static/init.js. |
| Snippet | A short copy-paste of HTML/JS. | The install tag that loads Smart Code on the customer site. |
| Beacon | A flare sent so someone far away knows you did something. | Event payload sent to the backend (typically /e) without waiting for a full page response. |
| Next.js | A toolkit for building React websites with file-based pages. | The framework for the CROForge frontend (app/ routes). |
| Enum | A labeled list of allowed values (like a dropdown in code). | Named numbers/strings in lib/enums.ts (statuses, roles, metric types, platforms). |
| Workspace | A shared office for a team. | Tenant container: users, websites, experiments, attributes, segments, metrics, events. |
Screenshot filename
Suggested screenshot filename: architecture-diagram.png. Capture a diagram of frontend ↔ backend ↔ customer website with Smart Code. Drop the real image into the WordPress Media Library and insert it here in place of this note.
System context
Three boxes talk to each other. The frontend is the CROForge product UI. The backend is the API that stores data and also serves init.js (compiles Smart Code for that workspace). The customer website loads that script. The site then sends beacons / events back to the backend when visitors see variations and convert.
┌─────────────────────┐ HTTPS/API ┌─────────────────────┐
│ CROForge Frontend │◄──────────────────►│ CROForge Backend │
│ (Next.js app) │ │ (API + init.js) │
└─────────────────────┘ └──────────┬──────────┘
│
beacon / events │ serves init.js
▼
┌─────────────────────┐
│ Customer website │
│ + Smart Code │
└─────────────────────┘Responsibilities
Each layer has a job. Keep UI in the frontend, persistence and compilation in the backend, and visitor-time decisions in Smart Code.
| Layer | Responsibility |
|---|---|
| Frontend | Auth UI, workspaces, experiment CRUD, Data Vista, settings, Monaco editor |
| Backend | Persistence, auth, compile/serve Smart Code per workspace, ingest events |
| Smart Code | Targeting, assignment, CSS/JS apply, event capture, integrations |
Key frontend modules
When you change product behavior, start in these paths. A module here just means a folder of related files.
| Path | Role |
|---|---|
app/ | Next.js routes (auth, workspace pages) |
components/ab-testing-page/ | Experiment UI pieces |
components/common/condition-rule/ | Shared condition builders |
lib/*.ts | API services, enums, schemas |
static/init.js | Reference / sample Smart Code bundle |
Data model (conceptual)
A data model is the family tree of records: what belongs to what. CROForge nests everything under a workspace.
- Workspace → Users, Websites, Experiments, Attributes, Segments, Metrics, Events
- Experiment → URL targeting, Variations,
segmentId,experimentMetrics - Variation →
trafficPercent,jsCode,cssCode,isControl
Enums (the labeled allowed values for status, role, metric type, and similar) live in lib/enums.ts.
