Development View

Module Architecture

Browser and State

• Editor.tsx coordinates editing, playback, saving, collaboration, and problem or daily-build mode. Its solution document is separate from the problem definition and can carry a problem_slug association.
• DiagramView.tsx draws a custom HTML canvas; it does not use React Flow, Mermaid, or D3. It handles state ports, pan/zoom, context menus, and diagram Undo/Redo snapshots.
• CodeEditor.tsx hosts CODE, TRANSITIONS, TESTS, COMPLEXITY, TREE, and AI modes. tmParser.tsx integrates CodeMirror with highlighting, completion, and Yjs.
• machineStore.ts maintains the machine, source, diagnostics, and shared positions. A diagram-edit epoch distinguishes local machine changes from incoming shared text so a stale local source does not overwrite the room.
• problemStore.ts and dailyStore.ts hold learning workflows and their API results. Daily UI includes guess tiles, probe/answer budgets, streaks, history, and a server-provided rollover countdown.

Compiler and Execution

The compiler is lexer -> parser -> analyzer -> assembler. The code editor collects parser and analyzer diagnostics; machine assembly and visualization can still use a partially valid parsed program.

USE_NEW_ASSEMBLER is currently true in the machine store. The older inline AST builder remains a code-level fallback, not a user-facing mode. engine/programMachine.ts centralizes label-to-ID mapping, transition normalization, position selection, tape alphabets, and well-formedness messages. Both the browser store and server-side daily authoring use this finalization without importing SolidJS runtime state into server compilation.

simulator.ts provides stepping, bounded runs, complexity metrics, and nondeterministic trees. marker.ts applies user tests; grader.ts validates and grades submitted machines against public and private problem cases. trace.ts supports black-box probes, tape/result prediction grading, and feedback tiles.

Server Boundaries

• SolidStart file routes provide pages and HTTP APIs; Nitro is the server runtime selected by the Vite configuration.
• lib/auth.ts configures Better Auth with GitHub and Google OAuth. lib/admin.ts checks the database's "user".role, not a Better Auth admin plugin.
• problemRepo.ts validates authored problems and projects cases by caller. dailyRepo.ts manages schedules, budgets, attempts, streaks, and visibility; dailyAuthoring.ts compiles references, generates observations and starter code, checks hidden-transition reachability, and self-grades drafts.
• api/ai/chat.ts builds an editor-context prompt and calls Groq using HTTP fetch; there is no dedicated Groq SDK dependency.
• server/plugins/yjs-ws.ts forwards WebSocket upgrades to a dedicated process. It does not own Yjs documents or persistence.

Source Map

Location in fla--	Responsibility
src/routes/index.tsx, editor.tsx, editor/[name].tsx, documents/[fileId].tsx	Dashboard, blank/example editors, saved documents
src/routes/problems/, create-problem.tsx	Catalog, problem solving, publishing
src/routes/daily/, admin/daily.tsx	Black-box and build dailies, scheduling interface
src/routes/api/auth/, files/, invites/, users/	Identity, document versions, access, invitations
src/routes/api/problems/, daily/, admin/daily/, ai/chat.ts	Grading, puzzle play, authoring, AI proxy
src/components/	Editors, visualization, forms, learning panels, theme
src/store/	Machine, problem, and daily state; code generation
src/engine/compiler/	Tokens, AST, parser, analyzer, assembler, completions
src/engine/	Simulator, marker, computational validation, grader, trace, finalization
src/lib/	Auth/database, repositories, authoring, clock, player cookie, AI prompt
src/collab/	Shared code/tests/positions and awareness
src/server/plugins/yjs-ws.ts	Production upgrade forwarding
yjs/yjs-server.mjs, yjs/package.json	Standalone WebSocket service and its dependencies
tests/engine/compiler/, colocated *.test.ts(x)	Compiler, engine, component, repository, and route tests
Dockerfile, Dockerfile.yjs, .gitea/workflows/	Build, coverage, and deployment definitions

Dependency and Tooling Sources

Use Tech Stack for runtime/build versions and Third-Party Code & Dependencies for the direct package inventory. Root and Yjs manifests are separate; the Yjs lockfile does not yet record every dependency in its current manifest.

The documentation site is a separate Docusaurus/React application. Its Mermaid diagrams and SVG wireframes are documentation assets, not application editor dependencies.