The Tech Stack

Application Stack

Layer	Technology / declared range	Role
UI	SolidJS ^1.9.14	Fine-grained reactive signals/stores and JSX components
Application framework	SolidStart ^2.0.0	File-based pages and server API handlers
Routing / metadata	@solidjs/router ^1.0.0, @solidjs/meta ^0.29.4	Navigation and page metadata
Build	Vite ^8.0.0	Development server and production bundling
Server runtime	Nitro ^3.0.260610-beta	SSR/API output and selectable deployment preset
Styling	Tailwind CSS / Vite plugin ^4.3.3	Utility styling alongside custom retro CSS
Text editor	CodeMirror ^6.0.2	Source and test editing, highlighting, completion, diagnostics
Diagram editor	Browser Canvas 2D API	Custom state/transition drawing and pointer interaction
Compiler and simulation	Project TypeScript modules	Lexer, parser, analyzer, assembler, finalization, simulator, marker, grader, trace
Authentication	Better Auth ^1.7.0	GitHub/Google sign-in and sessions
Database	PostgreSQL via pg ^8.23.0	Identity, document metadata, learning progress, and collaboration history
Collaboration	Yjs ^13.6.33, y-websocket ^3.1.0, y-codemirror.next ^0.3.6	Shared code, tests, positions, editor selections, presence
WebSocket service	ws ^8.18.0, @y/websocket-server ^0.1.0	Dedicated room service, separate from the Nitro app
Markdown	marked ^18.1.0	AI response rendering; problem statements use a custom Markdown-subset renderer
AI service	Groq HTTP API	Context-aware assistant; called with fetch, not an SDK
Runtime / deployment	Node.js >=24, Docker, Gitea Actions; alternative Vercel workflow	Application and Yjs containers, CI, deployment

SolidJS keeps frequent machine/tape/diagram updates local to affected reactive consumers. SolidStart keeps pages and HTTP APIs in one source tree. This does not mean the whole system is one process: PostgreSQL, file storage, and the Yjs room server remain separate services.

Current Architecture

The shared domain compiler and engine execute in the browser for editing and simulation, and on the server for puzzle authoring and grading. Problem definitions have public/private cases; daily puzzles use cookie-identified players, server budgets, and a configurable daily clock.

Collaboration and Persistence

Yjs supplies the CRDT model, y-codemirror.next binds source editing, and y-protocols carries awareness. The dedicated server owns room documents and PostgreSQL update logging/replay. Nitro's listener plugin only forwards upgrades. Explicit saves and enabled autosave still go through the Files API and retain the latest four JSON document versions in external storage.

Development and Tests

• npm run dev uses concurrently ^10.0.5 to start Vite and the Yjs process.
• npm run build runs vite build; npm start runs the Nitro Node output.
• Vitest ^5.0.0, jsdom ^29.1.1, Solid Testing Library ^0.8.10, and V8 coverage ^5.0.0 provide engine, compiler, component, repository, and route tests. See Testing Methodology.
• ESLint ^10.10.0, typescript-eslint ^8.70.0, and eslint-plugin-solid ^0.18.0 are declared tooling. The root manifest has no dedicated lint or type-check script and no direct typescript declaration; do not copy obsolete TypeScript version claims from earlier sprint docs.
• Express and CORS remain declared packages, but the main app's APIs use SolidStart, not a separate Express application. The external storage service's implementation is outside the inspected repository.

Deployment

The public editor is fla.capitalsigma.biz. The self-hosted workflow builds a Node 24 Alpine app container plus a Node 24 Slim Yjs container. A separate Vercel workflow still exists; neither should be confused with this documentation site's Cloudflare Pages deployment.

See Physical View for environment variables, network paths, workflow triggers, and observed configuration gaps.

Documentation Stack (Separate Repository)

This site uses Docusaurus 3.10.2, React ^19.0.0, TypeScript ~6.0.2, Mermaid ^11.17.1, and panzoom ^9.4.4. Mermaid architecture diagrams and SVG wireframes document the application; they do not power its visual editor.