CR-2026-03-25: Domus Digitalis AsciiDoc — Implementation

Deliverable 1: Seed Script

Problem

35 projects defined in projects.json needed to be loaded into PostgreSQL. Manual entry unacceptable.

Solution

Created prisma/seed.js with:

  • dotenv loading for DATABASE_URL

  • Slug generation from title

  • Upsert logic (create if new, update if exists)

  • Filter for valid project objects (skip comment-only entries)

Files Created

File Purpose

apps/backend/prisma/seed.js

Seed script (~125 lines)

apps/backend/prisma/seed-data/projects.json

35 projects with metadata (existed, populated earlier)

Key Code

require('dotenv').config();  // Critical - loads DATABASE_URL

const { PrismaClient } = require('@prisma/client');
const prisma = new PrismaClient();

// Filter out pure comment entries (objects with only _comment, no title)
const projects = data.projects.filter(p => p.title);

// Upsert logic using slug as unique identifier
const existing = await prisma.projects.findUnique({ where: { slug } });
if (existing) {
  await prisma.projects.update({ where: { slug }, data: projectData });
} else {
  await prisma.projects.create({ data: { ...projectData, slug } });
}

Execution Result

🏠 Domus Digitalis Project Seeder
────────────────────────────────────────

🌱 Seeding 35 projects...

  ✅ Created: Cisco ISE 3.4 Upgrade
  ✅ Created: iPSK Manager HA Deployment
  ... (8 more created)
  ✏️  Updated: Vault SSH Certificate Authority
  ✏️  Updated: Network Automation CLI
  ... (23 more updated)

📊 Seed Summary:
   Created: 10
   Updated: 25
   Errors:  0
   Total:   35

✨ Seeding complete!

Issues Encountered and Fixed

Issue Cause Fix

DATABASE_URL not found

dotenv not loaded

Added require('dotenv').config(); at top

Only 25 of 35 projects processed

Filter !p._comment excluded projects WITH _comment annotations

Changed to p.title to include all objects with titles

Deliverable 2: AsciiDoc Workspace Editor

Problem

Visual Atelier workspace (/atelier/workspace) had Mermaid, PlantUML, Draw.io but no AsciiDoc. User preference is AsciiDoc for all documentation.

Solution

Added AsciiDoc as fourth editor in Visual Atelier with:

  • Live preview using asciidoctor.js

  • 14 example templates (organized in 4 categories)

  • Export to HTML and .adoc

  • Save/Load via useDiagramStorage hook

  • Fullscreen preview mode

  • Share functionality

Files Modified

File Action Changes

app/atelier/workspace/layout.tsx

Modified

Added "Document Tools" category with AsciiDoc entry

app/atelier/workspace/page.tsx

Modified

Changed grid from 3 to 4 columns, added AsciiDoc card

app/atelier/workspace/asciidoc/page.tsx

Created

Full standalone editor (~1170 lines, includes 14 example templates)

Layout Changes

// Added new category in tools array
{
  category: 'Document Tools',
  items: [
    {
      icon: '📝',
      name: 'AsciiDoc',
      desc: 'Technical documentation',
      route: '/atelier/workspace/asciidoc',
      status: 'ready'
    }
  ]
}

Editor Features

Feature Implementation

Live Preview

asciidoctor.js with dynamic import (client-side only)

Templates

14 templates in 4 categories (see below)

Export HTML

Blob download with rendered HTML

Export .adoc

Blob download with source

Save/Load

useDiagramStorage('asciidoc') hook

Fullscreen

Preview-only fullscreen mode

Share

URL token generation

Example Templates Included (14 total)

Basics:

  • (1) Basic Document - Headers, paragraphs, lists

  • (2) Tables - Column specs, alignment

  • (3) Code Blocks - Source highlighting, callouts

  • (4) Admonitions - NOTE, TIP, WARNING, IMPORTANT, CAUTION

Advanced:

  • (5) Advanced Tables - Colspan, rowspan, AsciiDoc content in cells, nested tables

  • (6) Definition Lists - Glossary style, horizontal definitions, Q&A format

  • (7) Blocks & Quotes - Sidebars, blockquotes, verse, example blocks, open blocks

  • (8) Attributes & Variables - Document attributes, conditionals, counters

Macros & Formatting:

  • (9) UI Macros - kbd, menu, btn macros, icons, text formatting

  • (10) Footnotes & Anchors - Inline/named footnotes, custom anchors, bibliography

  • (11) Checklists - Task lists, nested checklists, project status tables

  • (12) Passthrough & Raw - Raw HTML, literal blocks, stem/math notation

Templates:

  • (13) Includes & Refs - Partial and example includes, cross-references

  • (14) Runbook Template - Phase structure with validation steps

Bug Fix: White Window / Narrow Fullscreen

Initial implementation had rendering issues:

Issue Root Cause Fix

White window (no preview)

html state started empty; asciidoctor loaded async with no loading indicator

Added asciidoctorLoading state, loading spinner, immediate initial conversion on load

Narrow fullscreen

max-w-4xl constrained width to ~896px

Changed to w-full max-w-none for full-width rendering

Textarea fixed height

h-[500px] instead of filling panel

Changed to flex-1 with h-full to fill available space

TypeScript errors

convert() returns string | Document; saveDiagram expected undefined not null

Added as string cast; changed null to undefined

HTML generated but invisible

@tailwindcss/typography not installed; prose classes did nothing

Installed plugin, added to tailwind.config.js plugins array
Typography Plugin Installation
cd apps/frontend
npm install @tailwindcss/typography
tailwind.config.js
plugins: [
  require('@tailwindcss/typography'),
],

Documentation Updates

File Changes

projects/personal/domus-digitalis/index.adoc

Created comprehensive project documentation with full stack enumeration

projects/index.adoc

Added Domus Digitalis to Personal Projects table