Aptlantis Studio — Architecture & System Design Document

Source: Docs/AptlantisStudio-Architecture&SystemDesignDocument.md (only version in the source tree — no shorter-named duplicate exists for this one).

This document describes the host application (Aptlantis Studio) that Neon Ink, NIPC, AIC, APGC, and SESM together govern. It is implementation-level detail, not a standard in itself, but it explains why NeonInk's other documents assume a Rust generator, JSON/JSONL data layer, and compiled SVG/HTML output model.

1. Overview

Aptlantis Studio is a data-driven platform for creating, curating, and distributing focused datasets for small, locally runnable models.

Unlike traditional web applications, Aptlantis Studio is not built as a dynamic frontend system. Instead, it operates as a:

Deterministic artifact compiler that transforms structured data into visual and navigable outputs

The system compiles:

• SVG-based visual components
• Static HTML pages
• Theme-driven UI artifacts

All derived from structured data sources such as JSON and JSONL.

2. Core Philosophy

2.1 Artifact-First Design

Every visual element is an artifact generated from data: dataset cards → SVG artifacts; pipeline states → visual artifacts; theme boards → metadata-rich SVGs.

2.2 Data as Source of Truth

No UI element is manually authored beyond templates. All content originates from dataset manifests, pipeline outputs, and theme definitions.

2.3 Static Output, Dynamic Generation

The system produces static files, but is frequently regeneratable, pipeline-driven, and event-triggered.

2.4 Local-First & Durable

No runtime dependencies required to view the site; fully mirrorable; long-term reproducible.

3. System Architecture

3.1 High-Level Flow

Data (JSON/JSONL)
      ↓
Rust Generator (themegen / aptstudio)
      ↓
Templates (SVG + HTML)
      ↓
Compiled Artifacts (SVG + HTML)
      ↓
Static Hosting (Caddy / filesystem)

4. Directory Structure

/AptStudio/

  /data/
    datasets.jsonl
    pipelines.jsonl
    stats.json
    themes.json

  /templates/
    /svg/
      dataset_card.svg.tmpl
      pipeline_panel.svg.tmpl
      theme_board.svg.tmpl

    /html/
      base.html
      dataset.html
      pipelines.html
      index.html

  /generated/
    /svg/
      /datasets/
      /pipelines/
      /themes/

    /html/
      /datasets/
      /pipelines/

  /static/
    /css/
    /icons/

  /tools/
    /aptstudio/   (Rust generator CLI)

  /public/
    (final compiled output served by Caddy)

5. Data Layer

5.1 Dataset Manifest (JSONL)

Each dataset is represented as a single record:

{
  "id": "rust_code_corpus",
  "name": "Rust Code Corpus",
  "state": "active",
  "type": "code",
  "tokens": 18700000000,
  "records": 532104,
  "updated": "2026-05-01"
}

5.2 Pipeline Manifest

{
  "id": "rust_pipeline",
  "status": "running",
  "progress": 72,
  "stage": "normalization"
}

5.3 Theme Tokens

{
  "colors": {
    "cyan": "#22D3EE",
    "violet": "#A78BFA",
    "magenta": "#F472B6"
  },
  "semantic": {
    "active": "cyan",
    "running": "violet",
    "featured": "magenta"
  }
}

6. Generator Layer (Rust)

6.1 Responsibilities

The Rust generator parses JSON/JSONL, validates structured data, maps semantic states to theme tokens, renders templates (SVG + HTML), and writes output to /public.

6.2 Core Crates

serde
serde_json
tera
walkdir
anyhow

6.3 Core Execution Model

load data
→ resolve theme mappings
→ render templates
→ write files

6.4 CLI Interface (Planned)

aptstudio build
aptstudio build --dataset rust
aptstudio build --themes
aptstudio validate

7. SVG Component System

7.1 Role of SVG

SVGs act as UI components, metadata containers, visual artifacts, and crawlable structured documents.

7.2 SVG Template Structure

<svg>
  <metadata>
    {
      "dataset": "{{ id }}",
      "state": "{{ state }}"
    }
  </metadata>

  <rect fill="{{ theme.panel }}" />
  <rect stroke="{{ accent }}" />

  <text>{{ name }}</text>
</svg>

7.3 Benefits

Resolution independent; easily themed; embeddable anywhere; machine-readable.

8. HTML Layer

8.1 Philosophy

HTML is a layout shell, not a rendering engine.

8.2 Example

<div class="panel">
  <img src="/svg/datasets/rust_code_corpus.svg">
</div>

8.3 Responsibilities

Layout composition, navigation, grouping artifacts.

9. Styling System

9.1 Technologies

Tailwind (extended) for tokens, colors, utilities. Bulma for layout structure.

9.2 Design Language

Meaning	Color
Structure	Cyan
Process	Violet
Discovery	Magenta
Success	Green
Warning	Yellow
Error	Red
Code/Rust	Orange

9.3 Glow Semantics

State	Visual
Idle	No glow
Active	Soft cyan glow
Running	Violet glow
Featured	Magenta glow
Error	Red glow

10. Build & Update Strategy

10.1 Event-Driven Rebuilds

Trigger rebuild when a dataset is updated, a pipeline completes, or stats change.

10.2 Build Command

cargo run --bin aptstudio -- build

10.3 Optional Watch Mode

Monitor /data/; auto-trigger rebuild.

10.4 Partial Rebuild (Future)

changed dataset → regenerate only related artifacts

11. Page Types

• Landing Page: overview panels, featured datasets, pipeline highlights.
• Dataset Page: dataset artifact SVG, metadata panels, download links.
• Pipeline Page: status panels, progress indicators, logs/steps.
• Theme Board Page: palette visualization, semantic mapping, SVG export.

12. Extensibility

12.1 Future Features

Dataset versioning, schema validation, artifact graph relationships, theme switching per dataset, exportable theme packs.

12.2 Plugin Model (Conceptual)

/templates/
  /dataset/
  /pipeline/
  /theme/

Each template set acts as a rendering plugin.

13. Key Advantages

• Durability: no runtime dependencies, fully static output.
• Consistency: UI derived from structured data.
• Reproducibility: artifacts can always be regenerated.
• Flexibility: easy to add new datasets, themes, or pages.
• Personal Workflow Alignment: integrates directly with existing Rust pipelines, avoids repetitive manual HTML work, enables creative visual expression.

14. Final Definition

Aptlantis Studio is:

A Rust-powered artifact compiler that transforms structured dataset pipelines into visual, navigable, and archivable static outputs.

15. Closing Notes

This system intentionally avoids heavy frontend frameworks, dynamic runtime complexity, and manual UI maintenance.

Instead, it embraces structure, determinism, composability, and long-term resilience.

End of Document