System Architecture

System Architecture

Architecture summary

DesignForge should begin as a modular monolith with strict package boundaries. A separate model-serving process or optional remote services may be deployed independently when their compute, security, or operational needs justify it. Avoid premature microservice decomposition.

Major subsystems

Subsystem	Responsibilities	Must not own
Application shell	Windows, menus, commands, shortcuts, preferences, document tabs, notifications, native integration	Authoritative design objects or compiler logic
Workspace UI	Canvas chrome, panels, inspectors, dialogs, contextual controls	Direct mutation of document objects outside commands
Document domain	Schema, pages, nodes, hierarchy, components, variables, styles, interactions, IDs and invariants	UI framework, model vendor, or generated output structure
Command/transaction engine	Validation, atomic mutations, undo/redo, transaction grouping, events, rollback	Rendering or model inference
Geometry and layout	Transforms, bounds, constraints, auto layout, grid/flex semantics, hit-test primitives	UI component state
Renderer	Visible scene rendering, viewport transforms, selection overlays, hit testing, invalidation	Document ownership
Asset service	Import validation, thumbnails, metadata, storage, references, export paths	Design hierarchy semantics
AI service	Context building, retrieval, planning, typed proposals, evaluation, repair, provider routing	Direct serialized-document mutation
Prototype engine	Interaction graph, runtime state, navigation, overlays, transitions, runtime diagnostics	A separate editable copy of design structure
React compiler	Intermediate representation, component/style/token emitters, assets, diagnostics and build validation	Mutating the source document
Project store	Versioned serialization, .dforge packaging, autosave journal, snapshots, recovery, migrations	UI rendering
Optional ecosystem	Collaboration, shared libraries, plugins, publishing, CLI and MCP adapters	Unapproved changes to existing public contracts

Data flow

Manual edit

User action → command → validation → transaction → canonical document update → layout/render projections refresh → autosave journal

AI edit

Prompt → context retrieval → typed plan → schema/scope validation → preview/diff → user approval → command transaction → document update

Prototype

Document snapshot + interaction graph + runtime configuration → prototype interpreter → player

Export

Stable document snapshot → compiler intermediate representation → component/layout/style generation → assets and manifest → validation/build checks → export package + diagnostics

Dependency direction

• UI depends on domain contracts and application services.
• Commands depend on the document domain and geometry/layout contracts.
• Renderer consumes read-only snapshots and resolved layout data.
• AI consumes document selectors and emits typed operations.
• Prototype runtime reads document semantics and interaction definitions.
• Compiler consumes a stable snapshot and emits files.
• Project store serializes domain state without importing UI components.

Avoid circular package dependencies. Add architecture tests or lint rules to enforce these boundaries.

Suggested repository organization

Adapt this to the current repository rather than moving existing code blindly.

apps/
  desktop/
  web-preview/
  model-service/                 # optional
packages/
  app-ui/
  domain-document/
  domain-commands/
  scene-graph/
  geometry/
  renderer-core/
  renderer-canvas/
  layout-engine/
  typography/
  asset-service/
  design-system/
  prototype-engine/
  ai-core/
  ai-model-adapters/
  react-compiler/
  project-store/
  shortcut-system/
  plugin-api/
  diagnostics/
  shared-types/
tools/
  designforge-cli/
  fixture-generator/
  migration-tools/
tests/
  integration/
  e2e/
  visual-regression/
  performance/
docs/
  architecture/
  schemas/
  adr/

Only create packages that are actively used and have clear ownership. Preserve the existing stack when practical and justify any new dependency, including its license and maintenance implications.