Viewer Server & Local APIs
Relevant source files
The following files were used as context for generating this wiki page:
The Delano Viewer is a packaged, read-only local UI designed for inspecting the delivery contracts stored within a repository's .project/ directory. It serves as an optional UI layer that provides a "local dossier" experience—offering warm paper themes, ledger-style typography, and visible source provenance for maintainers and operators.
The system consists of a Node.js-based server that indexes project state, including context, templates, and active projects, and exposes this data through local APIs. These APIs enable the frontend to render markdown, navigate workstream and task relationships, and apply context-aware filters without modifying the underlying source of truth on disk.
Sources: README.md:25-27, README.md:143-150, DESIGN.md:323-328
System Architecture
The Viewer operates as a standalone service launched via the Delano CLI. It uses a specific directory structure under .delano/viewer/ to house its server-side logic and static public assets.
Component Overview
- CLI Wrapper: The
delano viewercommand validates the environment and spawns the server process. - Node Server: Located at
.delano/viewer/server.js, it handles requests, manages port selection, and serves the UI. - Indexing Engine: Scans
.project/for specs, plans, workstreams, and tasks to build a project outline. - Static Assets: React-based frontend components (
app.js,app.jsx) and styles (styles.css) that implement the Design System.
Sources: src/cli/commands/viewer.js:52-70, README.md:120-128, package.json:28
Lifecycle and Data Flow
The following diagram illustrates the process of launching the viewer and how it interacts with the repository data.
The viewer is strictly read-only; it derives information from the file system but does not provide endpoints for mutating the .project/ state.
Sources: src/cli/commands/viewer.js:52-70, README.md:146-150, PRODUCT.md:23-25
Server Configuration
The viewer server defaults to http://127.0.0.1:3977. Configuration is primarily handled through environment variables and CLI arguments.
Configuration Parameters
| Option / Variable | Type | Default | Description |
|---|---|---|---|
--target <dir> | Argument | process.cwd() | The Delano repository directory to index and view. |
DELANO_VIEWER_PORT | Env Var | 3977 | The starting port for the local server. |
PORT | Env Var | 3977 | Fallback port variable if DELANO_VIEWER_PORT is unset. |
DELANO_VIEWER_ROOT | Env Var | Resolved Root | Internal variable passed to the server process to identify the repo. |
Sources: src/cli/commands/viewer.js:41-48, src/cli/commands/viewer.js:63-67
Execution Logic
When runViewer is invoked, the system identifies the getPackageRoot to locate the server script and findDelanoRoot to establish the working directory for data indexing. If the default port is busy, the server is designed to attempt starting on the next available port.
Sources: src/cli/commands/viewer.js:54-61, src/cli/commands/viewer.js:47-48
Local APIs and Indexing
The viewer indexes the three primary subdirectories of the project state to build its navigation tree and document views.
Indexed Data Structures
- Context Indexing: Reads
.project/context/to provide repository-wide background and boundaries. - Template Indexing: Reads
.project/templates/to show the structure available for new artifacts. - Project Outlines: Deeply indexes
.project/projects/<slug>/to identify:- Artifact Roles: Distinguishing between
spec.md,plan.md, anddecisions.md. - Relationships: Mapping tasks to their parent workstreams and tracking
depends_onorconflicts_withIDs. - Status Rollups: Summarizing project health based on individual task and workstream states.
- Artifact Roles: Distinguishing between
Sources: README.md:146-150, src/cli/lib/project-state.js:82-89, src/cli/lib/project-state.js:106-116
API Logic Diagram
The server provides endpoints that represent the structure found in the loadProjectState and loadProject library functions.
Visual Language Implementation
The viewer UI is the primary consumer of the project's Design System. It translates the "Local Dossier" creative north star into a functional browser interface.
UI Components and Constraints
- Sidebar: Fixed 232px width on desktop, containing project navigation and the
delano-mark.svg. - Document Reader: The signature component for rendering markdown with comfort-focused typography (15px body, 1.65 line height).
- Status Chips: Pill-shaped indicators that use a combination of labels and 6px status dots to indicate completion or blockers.
- Ledger Rows: Tables and summary strips use 1px hairline borders instead of cards to maintain a flat, operational feel.
Sources: DESIGN.md:200-210, DESIGN.md:323-328, DESIGN.md:255-265
Design Token Usage
| Element | Token / Value | Purpose |
|---|---|---|
| Background | document-bg | Warm neutral app background. |
| Surface | paper-surface | Sidebar and code block backgrounds. |
| Border | hairline | Structural 1px separators. |
| Active State | slate-accent | Subtle selection signal for navigation. |
Sources: DESIGN.md:110-125, DESIGN.md:143-150
Conclusion
The Viewer Server & Local APIs provide a specialized read-only interface for the Delano delivery runtime. By automating the indexing of .project contracts and serving them through a design-compliant web interface, the system ensures that project state remains accessible and traceable for both human operators and automated agents. Its architecture prioritizes non-destructive interaction, keeping the file-backed contracts as the ultimate source of truth while enhancing their legibility through a modern, local web stack.