Architecture Overview#

MonoForge follows a unidirectional data flow architecture designed for zero state drift and instant compilation speed:

BASH

┌─────────────────────────────────────────────────────────┐
│                      USER INTERFACE                     │
│  [ Visual Studio ]  [ Monaco IDE ]  [ Telemetry ] [ SVG ]│
└───────────────────────────┬─────────────────────────────┘
                            │ Read / Write
                            ▼
┌─────────────────────────────────────────────────────────┐
│                  SINGLE ZUSTAND STORE                   │
│             (src/store/useReadmeStore.ts)               │
└───────────────────────────┬─────────────────────────────┘
                            │ Pure Input
                            ▼
┌─────────────────────────────────────────────────────────┐
│                PURE COMPILER PIPELINE                   │
│               (src/lib/buildMarkdown.ts)                │
└───────────────────────────┬─────────────────────────────┘
                            │ Deterministic Markdown
                            ▼
┌─────────────────────────────────────────────────────────┐
│                 OUTPUT & DISTRIBUTION                   │
│   [ Live Preview ]  [ Clipboard ]  [ GitHub 1-Click Push ] │
└─────────────────────────────────────────────────────────┘

Data Flow Pipeline#

State Mutation: The user adjusts a control in the Visual Studio or types in Monaco.
Store Synchronization: The mutation updates useReadmeStore, which validates against ReadmeConfigSchema.
Pure Compilation: buildMarkdown(config) runs in milliseconds, compiling the profile AST into GitHub Flavored Markdown.
Sanitized Rendering: The markdown is rendered in the live preview using GitHub's sanitized HTML profile stylesheet.
Confirmation-Gated Push: When requested, the output diff is previewed and committed via GitHub REST API.

Repository Directory Map#

BASH

src/
├── app/                  # Next.js App Router (locale routing, API endpoints)
│   ├── [locale]/         # Localized pages (developer, templates, telemetry, docs)
│   └── api/              # API routes (enrichment, telemetry, schema)
├── components/           # UI components
│   ├── developer/        # Monaco editor, plugin panel, live preview, export bar
│   ├── docs/             # Documentation layout, sidebar, TOC, search modal
│   ├── studio/           # Visual studio controls, hero, bento grid
│   └── sync/             # GitHub OAuth, diff preview, commit modal
├── lib/                  # Core engines and utilities
│   ├── buildMarkdown.ts  # Pure markdown compiler (unit tested)
│   ├── plugins/          # Plugin registry and individual plugin modules
│   └── forge-telemetry/  # 47+ telemetry engines catalog and SVG builders
├── store/                # Unified Zustand store (useReadmeStore.ts)
└── content/docs/         # Documentation source data and metadata

Architecture Overview#

MonoForge follows a unidirectional data flow architecture designed for zero state drift and instant compilation speed:

BASH

┌─────────────────────────────────────────────────────────┐
│                      USER INTERFACE                     │
│  [ Visual Studio ]  [ Monaco IDE ]  [ Telemetry ] [ SVG ]│
└───────────────────────────┬─────────────────────────────┘
                            │ Read / Write
                            ▼
┌─────────────────────────────────────────────────────────┐
│                  SINGLE ZUSTAND STORE                   │
│             (src/store/useReadmeStore.ts)               │
└───────────────────────────┬─────────────────────────────┘
                            │ Pure Input
                            ▼
┌─────────────────────────────────────────────────────────┐
│                PURE COMPILER PIPELINE                   │
│               (src/lib/buildMarkdown.ts)                │
└───────────────────────────┬─────────────────────────────┘
                            │ Deterministic Markdown
                            ▼
┌─────────────────────────────────────────────────────────┐
│                 OUTPUT & DISTRIBUTION                   │
│   [ Live Preview ]  [ Clipboard ]  [ GitHub 1-Click Push ] │
└─────────────────────────────────────────────────────────┘

Data Flow Pipeline#

State Mutation: The user adjusts a control in the Visual Studio or types in Monaco.

Store Synchronization: The mutation updates useReadmeStore, which validates against ReadmeConfigSchema.

Pure Compilation: buildMarkdown(config) runs in milliseconds, compiling the profile AST into GitHub Flavored Markdown.

Sanitized Rendering: The markdown is rendered in the live preview using GitHub's sanitized HTML profile stylesheet.

Confirmation-Gated Push: When requested, the output diff is previewed and committed via GitHub REST API.

Repository Directory Map#

BASH

src/
├── app/                  # Next.js App Router (locale routing, API endpoints)
│   ├── [locale]/         # Localized pages (developer, templates, telemetry, docs)
│   └── api/              # API routes (enrichment, telemetry, schema)
├── components/           # UI components
│   ├── developer/        # Monaco editor, plugin panel, live preview, export bar
│   ├── docs/             # Documentation layout, sidebar, TOC, search modal
│   ├── studio/           # Visual studio controls, hero, bento grid
│   └── sync/             # GitHub OAuth, diff preview, commit modal
├── lib/                  # Core engines and utilities
│   ├── buildMarkdown.ts  # Pure markdown compiler (unit tested)
│   ├── plugins/          # Plugin registry and individual plugin modules
│   └── forge-telemetry/  # 47+ telemetry engines catalog and SVG builders
├── store/                # Unified Zustand store (useReadmeStore.ts)
└── content/docs/         # Documentation source data and metadata

System Architecture & Data Flow

Architecture Overview#

Data Flow Pipeline#

Repository Directory Map#

MonoForge

System Architecture & Data Flow

Architecture Overview#

Data Flow Pipeline#

Repository Directory Map#