Architecture

Atlas Forms is a 17-package pnpm monorepo built on a strict 3-tier architecture. Core packages have zero external dependencies. Every layer can only depend downward.

17-Package Monorepo

Packages are organized by responsibility. No upward dependencies — Layer N can only import from Layer N-1 or below.

Layer 3 — Presentation

React Components

player-components-react designer-components-react pages-player-react pages-studio-react ui-components-react controls-builtin-js controls-advanced-react

Form display (Player), visual designer (Studio), 89+ built-in controls, advanced media/chart controls. All React 18 + TypeScript.

↓

Layer 2 — Logic

Services, State & Storage

form-engine-js state-react api-client-js storage-js control-registry-js client-js themes-js

FormEngine state, Zustand bindings, HTTP client with 80%+ caching, LocalStorage/IndexedDB persistence, plugin registry, unified client service, theme management.

↓

Layer 1 — Foundation

Types, Schema & Validation

types-js schema-js validation-js

88+ TypeScript type definitions. O(n) JSON schema parser. 6 built-in validators + custom extension framework. Zero external dependencies.

Key packages explained

form-engine-js

Central form state machine. Manages all value changes, dirty/touched state, validation lifecycle, and form events. Framework-agnostic — works without React.

setFieldValue / getValues
validate() → ValidationResult
isDirty / isTouched / isSubmitting
Form snapshots (save/restore)
8 event types (change, blur, submit…)

api-client-js

HTTP integration layer with built-in caching, retry logic, and memory leak prevention. Four client classes cover all form API operations.

FormDefinitionApiClient
FormDataApiClient
FormCategoryApiClient
FormTypeApiClient
80%+ fewer API calls via cache

storage-js

Transparent storage layer with automatic fallback. Drafts and form records persist across sessions with quota management and auto-cleanup.

LocalStorageAdapter (5–10MB)
IndexedDBAdapter (100MB+)
Auto-fallback chain
Draft save / load / clear
Quota management & cleanup

validation-js

Extensible validation framework. Six built-in validators cover the common cases. Custom validators are registered by name and referenced in form schema.

required, length, numeric
pattern, email, url
Async validator support
Multi-field validators
Context-aware validation

control-registry-js

Singleton plugin registry for all 89+ controls plus any custom ones. Observer pattern notifies components when controls are registered or removed.

register / unregister
get / getAll / has / count
getGroups() by category
subscribe() for changes
Search functionality

themes-js

Theme management with OS preference detection. Register custom themes alongside built-in light and dark. All tokens cover colors, typography, spacing, radius, shadows, and transitions.

Light / Dark / Custom themes
watchSystemPreference()
toggle() Light ↔ Dark
Full token coverage
onChange() subscription

6-Layer Security Model

The HTML control is the highest-risk control in any form system. Atlas Forms blocks 28+ confirmed XSS attack vectors through 6 independent security layers — all enforced by default.

1

HTML5 Entity Encoding

All user-supplied text encoded before insertion. <script> becomes <script> — never executed.

2

Attribute Encoding

HTML attribute values double-encoded. Event handler injection (onclick=, onerror=) blocked at the attribute layer.

3

CSS Sanitization

Inline styles parsed and sanitized. expression(), javascript:, and behavior: properties stripped before rendering.

4

URL Validation

All href and src attributes validated. javascript: and data: URIs rejected. Only http://, https://, and relative paths allowed.

5

Tag Allowlist

Only a curated allowlist of HTML tags are permitted in rich content. script, iframe, object, embed, and form tags are removed regardless of encoding.

6

Content Security Policy

CSP headers enforced at the application layer. inline-script execution blocked. 40+ security tests covering all 28+ confirmed XSS vectors.

5 Operating Modes

Every control has per-mode visibility settings. Show different fields to users vs admins. Present read-only data in view mode. Let designers configure in design mode.

Mode	Editable	Primary use	Typical users
edit	Yes	Normal form filling	End users entering data in a workflow or standalone form
view	No	Read-only display	Reviewers, approvers checking a submitted record
design	Yes	Form building	Form designers and developers creating or editing form schema
admin	Yes	Administrative operations	Admins managing tenant forms, overriding values, audit review
preview	No	Testing with sample data	Designers and QA testing form appearance before publish

Data Flow

From user input to backend persistence — every step typed, validated, and tracked.

1

User Input

React component (FormField)

2

Hook

useAtlasForm() from state-react

3

State Engine

FormEngine dirty/touch tracking

4

Validation

validation-js → ValidationResult

5

API Client

api-client-js → Backend

6

Storage

Draft auto-save to localStorage / IndexedDB