SyncytiumMD / rules

---
description: Project architecture blueprint from .syncytium/architecture.md
alwaysApply: true
---
<!--
  ⚠️ AUTO-GENERATED BY SYNCYTIUM-MD ⚠️
  This file is automatically synchronized from .syncytium/
  Do not edit manually unless you plan to run reverse-sync.
  Source of truth: .syncytium/
-->

# 🏗️ Syncytium Architecture Blueprint

# System Architecture & Technology Stack

> Single source of truth for every AI agent working on this repository. Every
> bridge file (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/*.mdc`, …) is generated
> from this directory by `syncytium sync` — never edit those by hand.

## Overview

SyncytiumMD is a CLI + library + MCP server that maintains one canonical
context (`.syncytium/`) and transpiles it into the native instruction format of
every AI coding tool in use. It also provides multi-agent coordination: a
lease-based workspace lock, a handoff baton with an audit trail, and a local
visual knowledge graph.

## Technology Stack

- **Runtime:** Node.js 22.6+ (ESM, required by `node --experimental-strip-types`)
- **Language:** TypeScript, `strict` plus `noUnusedLocals`,
  `noUnusedParameters`, `noImplicitOverride`, `noImplicitReturns`,
  `verbatimModuleSyntax`
- **Build:** tsup (esbuild) with `dts: true` → `dist/{index,cli/index,mcp/index}.js`
- **CLI:** Commander.js + picocolors
- **Validation:** zod (config schema, rule frontmatter, ADR, every MCP tool input)
- **Parsing:** gray-matter (frontmatter) — all loaders deep-copy, see ADR-006
- **Watching:** chokidar
- **MCP:** `@modelcontextprotocol/sdk` over stdio
- **UI:** zero-dependency `node:http` server + a single-page Three.js app
  (Three.js r128 loaded from cdnjs; the vault/doc panels degrade gracefully
  without it)

## Module Map

| Path | Responsibility |
| --- | --- |
| `src/version.ts` | The single in-code version string; a unit test pins it to `package.json` |
| `src/core/schemas.ts` | Every zod schema: config, rule frontmatter, ADR, handoff, lock, stack |
| `src/core/paths.ts` | `slugify` (path-traversal guard), gitignore-style glob matcher, root containment |
| `src/core/diff.ts` | Dependency-free unified-diff generator used by `diff` |
| `src/core/storage.ts` | `.syncytium/` persistence, config validation/migration, ADR recovery |
| `src/core/templates.ts` | Per-stack rule sets (11 stacks), banners, CI workflow template |
| `src/core/engine.ts` | Orchestrator: init, sync, diff, doctor, lint, handoff, lock, graph, UI server, watch |
| `src/adapters/base.ts` | Shared compile helpers, rule-id sanitising, user-section preservation |
| `src/adapters/registry.ts` | Adapter registry, containment-checked writes, banner-only cleanup |
| `src/adapters/builtin/` | 10 built-in adapters + `GenericAdapter` for config-declared tools |
| `src/ui/markdown.ts` | Canonical Markdown → HTML renderer (injected into the browser bundle) |
| `src/ui/template.ts` | Obsidian Studio HTML: 3D graph, vault explorer, document reader |
| `src/mcp/server.ts` | 18 MCP tools, every input zod-validated, output token-budgeted |
| `src/cli/index.ts` | 22 CLI commands with a global `--json` mode |

## Engine API

`init` · `sync` · `diff` · `doctor` · `lint` · `validate` · `handoff` ·
`getHandoffHistory` · `addDecision` · `removeDecision` · `listDecisions` ·
`addRule` · `getRule` · `removeRule` · `listRules` · `exportBundle` ·
`clean` · `importExisting` · `getStatus` · `acquireLock` · `releaseLock` ·
`renewLock` · `getLockStatus` · `installGitHook` · `uninstallGitHook` ·
`installCiWorkflow` · `uninstallCiWorkflow` · `detectStack` ·
`getKnowledgeGraph` · `startUiServer` · `watch`

## Data Flow

```
.syncytium/  ──load──►  CanonicalContext  ──generate──►  GeneratedFile[]  ──write──►  bridge files
     ▲                                                                                        │
     └────────────────────  diff / prune / preserve user sections  ◄────────────────────────┘
```

`sync` writes every generated file, then prunes banner-tagged files that no rule
produces any more. `diff` compares content and reports `identical`, `modified`
(with a unified patch), `missing_on_disk`, and `unmanaged` (orphans).

## Directory Layout

- `src/` — source code and adapters
- `tests/syncytium.test.ts` — 114 tests, run by `node --experimental-strip-types --test`
- `scripts/release.mjs` — verify → publish → CDN-poll → global install
- `.syncytium/` — single source of truth
  - `rules/` — canonical, stack-aware rules
  - `memory/decisions.md` — ADRs
  - `memory/handoff-history.json` — baton audit trail
  - `memory/lock.json` — machine-local lease (git-ignored)
  - `HANDOFF.md` — live agent state