Core Concepts & Architecture Invariants

The Single Store Invariant#

MonoForge guarantees that profile state never drifts or becomes fragmented across different views. A single Zustand store located at:

src/store/useReadmeStore.ts

acts as the definitive source of truth. Whether a change is made through a visual slider, a badge toggle, an archetype preset, or the Monaco code editor, all updates are written directly to this store.

Pure Functional Compilation#

Markdown generation is handled strictly through a pure TypeScript function:

buildMarkdown(config: ReadmeConfig): string

Located at src/lib/buildMarkdown.ts, this function:

• Contains zero React hooks or UI dependencies.
• Has zero side effects and performs no network calls.
• Is covered by automated Vitest unit tests verifying deterministic output.

Any change to the profile output formatting must be implemented inside buildMarkdown.ts and verified against the test suite.

GitHub Camo Sanitizer Rules#

When GitHub displays images in a README, it routes all media URLs through GitHub Camo (https://camo.githubusercontent.com). Camo runs an aggressive security sanitizer that strips:

• All <script> elements.
• All <foreignObject> elements.
• External @import stylesheets and external font links.
• Javascript-driven animation hooks (onload, onclick).

MonoForge animated vectors and telemetry engines circumvent these limitations legally and safely by embedding all CSS animation rules inside self-contained <style> tags utilizing GPU-accelerated transform and opacity keyframes.

The Confirmation Gate Pattern#

MonoForge adheres to an ironclad privacy and safety rule:

• Resume Parsing: When parsing a PDF or DOCX file, extracted skills, links, and job titles appear in a review dialog (ConfirmGate.tsx). You select exactly which items to import.
• GitHub Sync: Before committing changes to your GitHub profile repository, MonoForge fetches your existing remote README, renders a line-by-line colored diff preview (DiffPreview.tsx), and requires an explicit confirmation click.