Architecture Overview

System layers

packages/contracts
├── document-engine
├── component-registry ── core-components
├── react-renderer
├── react-codegen
├── tsx-compiler
└── project-scaffold

apps/studio
├── Project Explorer / Source / UI Nodes / Inspector / Problems
├── derived and managed application previews
└── Tauri boundary ── studio-core ── project-store

apps/vscode-srijika
└── shared compiler diagnostics and quick fixes

The application source contract is equally strict: private behavior rises from Part → Slot → Feature and reaches src/shared only when two Features need it. Shared code is one of pure UI, UI+Connector Widget, or UI-less Headless Capability; it never imports a Feature or creates freehand utility folders. CLI, VS Code, Studio, and MCP all consume the same creation and validation contract.

That shared contract also enforces behavior-free UI, passive Types, canonical kebab-case owner names, and acyclic Shared runtime dependencies. Only a matching Connector renders an owner UI; parent/sibling composition uses the child Connector, except for pure UI composition of a canonical Shared UI Primitive. SRIJIKA4116 identifies a direct-child-UI violation and SRIJIKA4117 identifies runtime content or runtime consumption of a passive Types contract. SRIJIKA4118 keeps Logic framework-free: pure validation and transforms remain, while React, query-cache, router, and client-state lifecycle move to their Hook, Connector, or Store owners. Every UI also rejects external runtime behavior, not only private Srijika layers.

The import graph also fails closed. SRIJIKA4119 rejects computed import()/require() targets inside governed roots, SRIJIKA4120 rejects declared or reserved project aliases that do not resolve to scanned governed source, and SRIJIKA4121 rejects missing or outside-root relative/src/... source imports from governed files. CSS/static assets are exempt; external dependencies use bare package specifiers.

Custom architecture roots, structural directories, and suffixes are resolved from srijika.config.json through one safety boundary. Roots remain bounded, project-relative, and non-overlapping; directory names and suffixes remain case-insensitively distinct and basename-safe; no configured suffix may end with another; traversal, absolute paths, backslashes, and symlink escapes are rejected before any adapter reads or writes source. With no architecture block, canonical defaults apply. With an explicit block, profile feature-slot-part-v1 is mandatory and any missing/unsupported profile fails closed everywhere. Generated validation reloads the current config. check --watch uses a filtered project-root watcher for config, root tsconfig.json, entry, resolved roots, and future-root ancestors and recovers after temporarily invalid edits. VS Code/Studio path previews are canonical planner output rather than hardcoded UI strings.

Adopt an existing repository in stages

Add the versioned adoption.ownership contract to bound existing feature roots, recognize ui/, connectors/, and hooks/, explicitly categorize server/service/domain/test code, and mark complete owners as adopted. Srijika strictly validates adopted owners while reporting all remaining source as pending or excluded. The resolved no-write plan includes deterministic no-overwrite canonical moves and exact static import rewires; partial coverage never counts as full-project success. Run srijika adoption plan --json to inspect the plan before changing source.

The complete project contract requires sourceOfTruth: "tsx" and a normalized project-relative entry ending in the resolved UI suffix. The entry remains a strict, counted UI even outside both ownership roots. The architecture block has twelve optional override fields: two roots, four structural directories, and six suffixes. Root tsconfig.json is parsed as JSONC: extends is rejected, references must be absent or empty, and compilerOptions.baseUrl must be omitted. Only exact and slash-delimited terminal /* compilerOptions.paths mappings are portable, and a Vite-only alias is unsupported until mirrored there.

Readers reject symlinked roots, configs, sources, and ancestors. Config reads are capped at 64 KiB, tsconfig.json at 1 MiB, and a complete validation or migration scan at 4,096 TS/JS sources, 32,768 entries, 4,096 directories, depth 32, 4 MiB per source, and 24 MiB total. Hook/Store expansion rewires that full safe project corpus before moving the flat gateway. Studio live preview uses the configured entry, UI suffix, and matching Connector suffix.

Compile and edit path

resolved UI source
  → parse restricted TSX without executing the module
  → emit diagnostics and stable source locations
  → derive and validate UiDocument
  → project hierarchy + Inspector + React DOM

supported editor intent
  → bounded AST edit
  → expected-hash validation
  → atomic save
  → compile again

Persisted versus derived state

The source persists JSX, contracts, expressions, imports, comments, and developer formatting. UiDocument, hierarchy nodes, Inspector shapes, and preview DOM are derived. Selection, current diagnostics, dirty state, disk hashes, and stale-preview status belong to the editor session.

Native boundary

Tauri and Rust provide narrow operations for project creation, scanning, source loading and saving, VS Code navigation, and managed application lifecycle. The boundary rejects traversal, unsafe symlinks, invalid extensions, oversized files, stale hashes, arbitrary process arguments, and URLs not derived from a tracked application.

AI boundary

AI receives the same TSX rules and diagnostics as developers. It must propose changes to source and connector files. It may not persist or mutate derived UiDocument as a parallel authority.

Next.js adapter boundary

Next.js UI support is explicit and non-executing. The versioned adapter maps exact next/link and next/image imports, plus project-registered pure presentation components, to safe preview nodes. App Router pages, layouts, and route handlers share server/client and serializable-prop diagnostics across Studio, VS Code, CLI, and MCP. Unsupported, dynamic, invalid-prop, client-only, and non-serializable cases use stable SRIJIKA5001 through SRIJIKA5005 codes.

For the complete invariant list and dependency explanation, read the canonical Srijika Studio Architecture reference.