# apotheosys1982/chat-first-surface-shell architecture
> Architecture diagram of the GitHub repository apotheosys1982/chat-first-surface-shell, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/apotheosys1982/chat-first-surface-shell
- Repository: https://github.com/apotheosys1982/chat-first-surface-shell
## Overview
1. This repository is a standalone, static browser prototype for a “chat-first” assistant shell. The app is not a full backend service; the runtime surface is the HTML/CSS/JS bundle under `assistants/chat-first-surface-shell/public`, mirrored into `dist/chat-first-surface-shell` for deployment.
2. The entry point is a single-page browser app: `public/index.html` loads the shell script, styles, motion CSS, and supporting data files. Netlify is the publishing target, and the repo is structured so the source app directory is what gets deployed directly.
3. The main interactive subsystem is the chat shell itself, centered on the composer. The README makes clear that the composer is treated as the command line for the surface, and the shell is intentionally “chat-first” rather than a generic dashboard. This is the first screen and the primary control surface.
4. Artifact handling is a distinct routing boundary. The shell prioritizes “artifact commands” over natural-language answer-room routing, and registered artifacts open in a full-viewport artifact layer. That means command interpretation and artifact presentation are a separate path from ordinary chat responses.
5. Uploaded or imported files are quarantined rather than becoming trusted sources automatically. The presence of `source-registry.js`, `state-events.js`, `project-state.js`, and the “source inbox” planning/history files suggests a source-ingestion pipeline with explicit approval/state transitions instead of immediate activation.
6. State management appears to be split across a few small client-side modules: `project-state.js` for persisted shell state, `state-events.js` for state change events, and `source-registry.js` for tracking approved sources/artifacts. This suggests a lightweight evented state model rather than a server-backed store.
7. Rendering is decomposed into shell chrome, content area, and motion/transition concerns. The `motion/` directory contains shared-element and view-transition CSS libraries plus motion tokens, indicating that view changes and full-viewport artifact transitions are a first-class UI concern rather than incidental styling.
8. There is explicit support for a fallback-capable “HTML-in-Canvas” or canvas document stage. The repository contains a validation script for this (`validate-chat-first-html-canvas-stage.js`) and associated planning/evaluation docs, implying the app can attempt native canvas-based document rendering when browser APIs allow it, but must report DOM fallback honestly when they do not.
9. The viewport and scrolling behavior are constrained as part of the product architecture. Multiple planning/checksum items reference viewport lock, scroll stability, chrome direction, and offscreen tray behavior, which indicates the shell is designed to stay vertically constrained on both mobile and desktop and avoid horizontal pan or clipped UI regions.
10. The build/deployment workflow is simple but tightly governed. `tools/compile-chat-first-answer-pack.js` produces `public/compiled-answer-pack.js`, `tools/sync-chat-first-state.js` keeps source and mirror state aligned, and the various `validate-*` scripts enforce shell, routing, ingestion, rendering, and checksum invariants. The `checksums/`, `receipts/`, and `logs/` directories show an audit trail for these validation passes.
11. The repo also contains a substantial planning-and-handoff layer (`docs/`, `receipts/`, `logs/`, top-level `PLANNING_*.md`, `HANDOFF_*.md`). These files are not runtime subsystems, but they are part of the architecture process: they document design decisions for routing, premium UI, artifact lifecycle, and live evaluation protocols.
12. In deployment terms, the architecture is “source app + mirrored dist bundle + static host.” Local development uses Python’s built-in HTTP server, while production is Netlify. That means the critical boundary is not an API tier, but consistency between the source directory, the compiled answer pack, and the published mirror.
Main entry points: [`assistants/chat-first-surface-shell/public/script.js`](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/script.js) (Shell script), [`assistants/chat-first-surface-shell/public/index.html`](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/index.html) (Index page), [`tools/validate-chat-first-shell.js`](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/tools/validate-chat-first-shell.js) (Validators), [`docs/ARCHITECTURE.md`](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/docs/ARCHITECTURE.md) (Architecture docs)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_group_runtime["Runtime surface"]
node_node_public_index["Index page
spa entry
[index.html]"]
node_node_shell_script["Shell script
ui runtime
[script.js]"]
node_node_styles["Shell styles
ui styles
[styles.css]"]
node_node_answer_pack["Answer pack
compiled runtime data"]
node_node_deployment["Netlify deploy
static host
[netlify.toml]"]
end
subgraph group_group_state["Shell state"]
node_node_project_state["Project state
persisted state
[project-state.js]"]
node_node_state_events["State events
event model
[state-events.js]"]
node_node_source_registry["Source registry
source ledger
[source-registry.js]"]
node_node_artifact_router["Artifact router
routing boundary"]
node_node_canvas_stage["Canvas stage
render stage"]
end
subgraph group_group_motion["Motion layer"]
node_node_motion_tokens["Motion tokens
motion css
[motion-tokens.css]"]
node_node_shared_motion["Shared motion
transition css"]
node_node_view_transition["View transitions
transition css"]
end
subgraph group_group_tooling["Build and validation"]
node_node_compile_tool["Compile pack
build tool"]
node_node_sync_tool["State sync
build tool"]
node_node_validation_suite["Validators
invariant checks"]
end
subgraph group_group_docs["Planning and audit"]
node_node_readme_root["Repo README
entry/docs
[README.md]"]
node_node_shell_readme["Shell README
app docs
[README.md]"]
node_node_architecture_docs["Architecture docs
design docs
[ARCHITECTURE.md]"]
end
node_node_readme_root -->|"points to"| node_node_shell_readme
node_node_shell_readme -->|"defines entry"| node_node_public_index
node_node_public_index -->|"loads"| node_node_shell_script
node_node_public_index -->|"loads"| node_node_styles
node_node_public_index -->|"loads"| node_node_motion_tokens
node_node_shell_script -->|"persists"| node_node_project_state
node_node_shell_script -->|"emits"| node_node_state_events
node_node_shell_script -->|"routes through"| node_node_source_registry
node_node_shell_script -->|"dispatches"| node_node_artifact_router
node_node_shell_script -->|"renders via"| node_node_canvas_stage
node_node_shell_script -->|"uses"| node_node_shared_motion
node_node_shell_script -->|"uses"| node_node_view_transition
node_node_compile_tool -->|"produces"| node_node_answer_pack
node_node_sync_tool -->|"aligns"| node_node_project_state
node_node_validation_suite -->|"checks"| node_node_shell_script
node_node_validation_suite -->|"checks"| node_node_artifact_router
node_node_validation_suite -->|"checks"| node_node_canvas_stage
node_node_validation_suite -->|"checks"| node_node_public_index
node_node_deployment -->|"publishes"| node_node_public_index
node_node_architecture_docs -.->|"documents"| node_node_artifact_router
node_node_architecture_docs -.->|"documents"| node_node_canvas_stage
node_node_architecture_docs -.->|"documents"| node_node_validation_suite
node_node_architecture_docs -.->|"documents"| node_node_deployment
click node_node_readme_root "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/README.md"
click node_node_shell_readme "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/README.md"
click node_node_public_index "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/index.html"
click node_node_shell_script "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/script.js"
click node_node_styles "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/styles.css"
click node_node_answer_pack "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/compiled-answer-pack.js"
click node_node_project_state "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/project-state.js"
click node_node_state_events "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/state-events.js"
click node_node_source_registry "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/source-registry.js"
click node_node_motion_tokens "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/motion/motion-tokens.css"
click node_node_shared_motion "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/motion/shared-element-library.css"
click node_node_view_transition "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/motion/view-transition-library.css"
click node_node_compile_tool "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/tools/compile-chat-first-answer-pack.js"
click node_node_sync_tool "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/tools/sync-chat-first-state.js"
click node_node_validation_suite "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/tools/validate-chat-first-shell.js"
click node_node_artifact_router "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/tools/validate-chat-first-artifact-router.js"
click node_node_canvas_stage "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/tools/validate-chat-first-html-canvas-stage.js"
click node_node_deployment "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/netlify.toml"
click node_node_architecture_docs "https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/docs/ARCHITECTURE.md"
classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_public_index,node_node_shell_script,node_node_styles,node_node_answer_pack,node_node_deployment toneBlue
class node_node_project_state,node_node_state_events,node_node_source_registry,node_node_artifact_router,node_node_canvas_stage toneAmber
class node_node_motion_tokens,node_node_shared_motion,node_node_view_transition toneMint
class node_node_compile_tool,node_node_sync_tool,node_node_validation_suite toneRose
class node_node_readme_root,node_node_shell_readme,node_node_architecture_docs toneIndigo
```
## Components
### Runtime surface
Static browser shell and its mirrored deployment bundle.
- [Index page](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/index.html): spa entry · Browser entry point that loads the shell bundle and supporting assets. · `assistants/chat-first-surface-shell/public/index.html`
- [Shell script](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/script.js): ui runtime · Primary client-side application logic for the chat-first surface. · `assistants/chat-first-surface-shell/public/script.js`
- [Shell styles](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/styles.css): ui styles · Core presentation for chrome, layout, and shell surface behavior. · `assistants/chat-first-surface-shell/public/styles.css`
- [Answer pack](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/compiled-answer-pack.js): compiled runtime data · Generated pack consumed by the browser shell for assistant answers and routing support. · `assistants/chat-first-surface-shell/public/compiled-answer-pack.js`
- [Netlify deploy](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/netlify.toml): static host · Publishes the mirrored static bundle as the production host target. · `netlify.toml`
### Shell state
Client-side state, registry, and routing boundaries inside the app.
- [Project state](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/project-state.js): persisted state · Client-side persisted shell state for the current session and workspace. · `assistants/chat-first-surface-shell/public/project-state.js`
- [State events](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/state-events.js): event model · Event layer for state transitions and shell activity. · `assistants/chat-first-surface-shell/public/state-events.js`
- [Source registry](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/source-registry.js): source ledger · Tracks approved sources and artifact registration, separating trusted sources from quarantined imports. · `assistants/chat-first-surface-shell/public/source-registry.js`
- [Artifact router](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/tools/validate-chat-first-artifact-router.js): routing boundary · Prioritizes artifact commands and canonical open paths before ordinary chat routing. · `tools/validate-chat-first-artifact-router.js`
- [Canvas stage](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/tools/validate-chat-first-html-canvas-stage.js): render stage · Validates the fallback-capable HTML-in-Canvas document stage. · `tools/validate-chat-first-html-canvas-stage.js`
### Motion layer
Transition and shared-element styling used by the shell and artifact views.
- [Motion tokens](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/motion/motion-tokens.css): motion css · Shared motion variables and timing tokens for shell transitions. · `assistants/chat-first-surface-shell/public/motion/motion-tokens.css`
- [Shared motion](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/motion/shared-element-library.css): transition css · Shared-element transition styling for cross-view movement. · `assistants/chat-first-surface-shell/public/motion/shared-element-library.css`
- [View transitions](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/public/motion/view-transition-library.css): transition css · View-transition rules for full-viewport and artifact-layer changes. · `assistants/chat-first-surface-shell/public/motion/view-transition-library.css`
### Build and validation
Compile, sync, and invariant checks for the repository.
- [Compile pack](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/tools/compile-chat-first-answer-pack.js): build tool · Builds the compiled answer pack consumed by the shell. · `tools/compile-chat-first-answer-pack.js`
- [State sync](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/tools/sync-chat-first-state.js): build tool · Keeps source and mirrored state aligned between source app and dist bundle. · `tools/sync-chat-first-state.js`
- [Validators](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/tools/validate-chat-first-shell.js): invariant checks · Repository checks for shell behavior, routing, ingestion, renderer contracts, and syntax. · `tools/validate-chat-first-shell.js`
### Planning and audit
Architectural docs, handoffs, receipts, logs, and checksums.
- [Repo README](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/README.md): entry/docs · Top-level orientation for the standalone repository and deployment model. · `README.md`
- [Shell README](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/assistants/chat-first-surface-shell/README.md): app docs · Explains the chat-first surface shell, composer-centric interaction model, and deployment shape. · `assistants/chat-first-surface-shell/README.md`
- [Architecture docs](https://github.com/apotheosys1982/chat-first-surface-shell/blob/main/docs/ARCHITECTURE.md): design docs · Cross-cutting planning and architecture notes for routing, UI, artifact lifecycle, and evaluation. · `docs/ARCHITECTURE.md`
## Connections
- Repo README → Shell README: points to · Repository overview flows into the shell-specific README.
- Shell README → Index page: defines entry · The shell README describes the browser entry surface.
- Index page → Shell script: loads · The SPA bootstraps the main client runtime.
- Index page → Shell styles: loads · The entry page includes core shell styling.
- Index page → Motion tokens: loads · Motion tokens support the shell's transition system.
- Shell script → Project state: persists · The shell runtime reads and writes persisted state.
- Shell script → State events: emits · State changes are modeled as events.
- Shell script → Source registry: routes through · Artifact and source handling use the registry boundary.
- Shell script → Artifact router: dispatches · Command interpretation separates artifact paths from chat answers.
- Shell script → Canvas stage: renders via · Document stage behavior is part of the interactive render path.
- Shell script → Shared motion: uses · Shared-element transitions coordinate shell and artifact views.
- Shell script → View transitions: uses · Fullscreen artifact and view changes rely on view-transition rules.
- Compile pack → Answer pack: produces · Build step generates the compiled answer pack shipped with the app.
- State sync → Project state: aligns · Synchronization keeps source and mirrored state consistent.
- Validators → Shell script: checks · Shell behavior is validated as part of the invariant suite.
- Validators → Artifact router: checks · Routing rules are validated explicitly.
- Validators → Canvas stage: checks · Canvas-stage fallback behavior is validated explicitly.
- Validators → Index page: checks · Entry-page and bundle wiring are part of shell validation.
- Netlify deploy → Index page: publishes · Production hosting serves the source app bundle as static content.
- Architecture docs → Artifact router: documents · Architecture docs record the routing and artifact lifecycle design.
- Architecture docs → Canvas stage: documents · Docs capture the HTML-in-Canvas spike and evaluation protocol.
- Architecture docs → Validators: documents · Validation expectations and evaluation process are documented.
- Architecture docs → Netlify deploy: documents · Deployment and mirrored-bundle conventions are covered in docs.