Documentation Portal Architecture

The Mallnline platform documentation is split into two independent Astro 6 static sites, decoupled from the main SvelteKit frontend monolith (ngwenya-front). This separation enables faster builds, independent deployment, and cleaner ownership boundaries as the team onboards new developers ahead of native app development.

Why the Split?

Before this migration, all ~150 markdown docs lived inside ngwenya-front under src/lib/docs/ and src/lib/support/manuals/, rendered by custom Svelte components (DocRenderer, DocTOC). This created several problems:

1. Build bloat — Every documentation change triggered a full SvelteKit rebuild
2. Coupling — Documentation routes, utilities, and styles cluttered the app codebase
3. Deployment — Docs couldn't be deployed independently; a typo fix required a full frontend deploy
4. Onboarding overhead — New developers had to navigate a monolith to find docs

The Astro migration solves all of these with sub-2-second builds, zero-config content collections, and independent nginx-served static deployments.

Repository Structure

Developer Portal (`ngwenya-dev`)

ngwenya-dev/
├── src/
│   ├── content/docs/           # 86+ markdown articles
│   │   ├── overview.md         # Landing page content
│   │   ├── *.md                # Architecture, Management, etc.
│   │   └── subgraphs/          # Per-subgraph references
│   │       ├── auth.md
│   │       ├── uchat.md
│   │       └── ...
│   ├── components/
│   │   ├── Sidebar.astro       # Auto-discovered nav from frontmatter
│   │   ├── DocTOC.astro        # IntersectionObserver-based TOC
│   │   └── ThemeToggle.astro   # Dark mode toggle (localStorage)
│   ├── layouts/
│   │   ├── BaseLayout.astro    # HTML shell, fonts, theme init
│   │   └── DocLayout.astro     # Sidebar + content + mobile topbar
│   ├── pages/
│   │   ├── index.astro         # Renders overview.md
│   │   └── [slug].astro        # Dynamic doc pages (SSG)
│   ├── styles/
│   │   ├── tokens.css          # $mall design tokens (light + dark)
│   │   ├── global.css          # Resets, typography, scrollbar
│   │   └── doc-renderer.css    # Headings, code, tables, alerts
│   └── utils/
│       ├── docUtils.ts         # Markdown parser, frontmatter, TOC
│       └── portalUrls.ts       # Env-driven external URLs
├── .env                        # Local dev URL overrides
├── Dockerfile                  # pnpm build → nginx serve
└── astro.config.mjs            # SSG output, Svelte integration

Support Center (`ngwenya-support`)

Same structure, with src/content/manuals/ instead of src/content/docs/, and a SupportLayout with topic-card home page instead of the doc index.

Environment-Driven URL Management

All cross-portal links use centralized configuration rather than hardcoded production URLs. This enables seamless local development where all three apps run simultaneously.

URL Config Files

Each repo has a src/utils/portalUrls.ts (or $lib/config/portalUrls.ts in SvelteKit):

ngwenya-front — src/lib/config/portalUrls.ts

import { PUBLIC_DEVELOPER_PORTAL_URL, PUBLIC_SUPPORT_CENTER_URL } from '$env/static/public';

export const DEVELOPER_PORTAL_URL =
  PUBLIC_DEVELOPER_PORTAL_URL || 'https://developer.mallnline.com';
export const SUPPORT_CENTER_URL =
  PUBLIC_SUPPORT_CENTER_URL || 'https://support.mallnline.com';

ngwenya-dev — src/utils/portalUrls.ts

export const MAIN_APP_URL =
  import.meta.env.PUBLIC_MAIN_APP_URL || 'https://mallnline.com';
export const SUPPORT_CENTER_URL =
  import.meta.env.PUBLIC_SUPPORT_CENTER_URL || 'https://support.mallnline.com';

ngwenya-support — src/utils/portalUrls.ts

export const MAIN_APP_URL =
  import.meta.env.PUBLIC_MAIN_APP_URL || 'https://mallnline.com';
export const DEVELOPER_PORTAL_URL =
  import.meta.env.PUBLIC_DEVELOPER_PORTAL_URL || 'https://developer.mallnline.com';

Environment Variable Matrix

Local `.env` Overrides

Each repo's .env points to the corresponding localhost ports:

# ngwenya-front/.env
PUBLIC_DEVELOPER_PORTAL_URL=http://localhost:4321
PUBLIC_SUPPORT_CENTER_URL=http://localhost:4322

# ngwenya-dev/.env
PUBLIC_MAIN_APP_URL=http://localhost:5173
PUBLIC_SUPPORT_CENTER_URL=http://localhost:4322

# ngwenya-support/.env
PUBLIC_MAIN_APP_URL=http://localhost:5173
PUBLIC_DEVELOPER_PORTAL_URL=http://localhost:4321

Local Development

Starting All Five Apps

The ngwenya-front/Makefile orchestrates all five frontend applications:

# Start everything: frontend (5173) + Tower (5170) + Deck (5171) + dev portal (4321) + support center (4322)
make ui

# Or start apps individually
make tower-ui        # localhost:5170
make deck-ui         # localhost:5171
make dev-portal       # localhost:4321
make support-center   # localhost:4322

# Start both portals without the main frontend
make docs-dev

# Build both for production
make docs-build

# Install workspace dependencies (resolves @ngwenya/queries)
make install

The make ui target starts the doc portals, Tower, and Deck as background processes, then runs the main Vite dev server in the foreground. Ctrl+C kills all five. The kill-ports target cleans up all ports (5170–5179, 4173, 4321, 4322).

Adding New Documentation

Both portals use zero-config content discovery. Drop a .md file into the content directory with valid frontmatter and it's automatically picked up by the sidebar, routing, and build:

# Developer doc
vi ngwenya-dev/src/content/docs/my-new-feature.md

# Support manual
vi ngwenya-support/src/content/manuals/my-new-guide.md

See the agent workflows at .agent/workflows/create-developer-doc.md and .agent/workflows/create-support-doc.md for the full content creation process.

Design System Parity

Both portals share the same $mall design token system as the main frontend:

• tokens.css — Color palette (light + dark), typography, spacing, radius, shadows
• Dark mode — body.dark-mode class toggled via ThemeToggle, persisted in localStorage under mall-theme, supports prefers-color-scheme auto-detection
• Flash prevention — BaseLayout includes an inline <script is:inline> that runs before paint to set the correct class

The adaptive token system provides automatic theming:

:root {
  --mall-bg: var(--mall-light-bg);
  --mall-text: var(--mall-light-text);
}

body.dark-mode {
  --mall-bg: var(--mall-dark-bg);
  --mall-text: var(--mall-dark-text);
}

Build & Deployment

Static Site Generation (SSG)

Both portals output fully static HTML — no server-side rendering needed:

cd ngwenya-dev && pnpm build    # → dist/ (106 pages, ~6s)
cd ngwenya-support && pnpm build # → dist/ (55 pages, ~1s)

Docker/Podman

Each repo includes a two-stage Dockerfile:

1. Build stage — node:20-alpine with pnpm, runs pnpm build
2. Serve stage — nginx:alpine, copies dist/ into /usr/share/nginx/html

podman build -t mallnline-dev-portal ./ngwenya-dev
podman build -t mallnline-support-center ./ngwenya-support

Production Routing

On the VPS, configure the reverse proxy (Nginx/Caddy) to route:

Content Rendering Pipeline

Both portals share a docUtils.ts that handles the markdown-to-HTML pipeline:

1. Frontmatter extraction — YAML block parsed into metadata object
2. Cross-portal URL rewriting — remarkPortalUrls remark plugin rewrites hardcoded production URLs (https://developer.mallnline.com, https://support.mallnline.com, https://mallnline.com) to env-driven values at build time via unist-util-visit AST traversal
3. GitHub-style alerts — > [!NOTE], > [!WARNING], etc. converted to styled <div class="doc-alert-*"> blocks
4. Table of Contents — H2/H3 headings extracted with slug-ified IDs for anchor links
5. Mermaid diagrams — language-mermaid code blocks lazy-loaded client-side via dynamic import('mermaid'); theme auto-switches between default and dark based on body.dark-mode
6. Heading anchors — All H2/H3 elements get id attributes for deep linking and scroll-margin-top for sticky header offset

remarkPortalUrls Plugin

Located at src/utils/remarkPortalUrls.mjs in both portals. Registered in astro.config.mjs under markdown.remarkPlugins.

// Rewrites markdown link URLs at build time:
// https://developer.mallnline.com/slug → $PUBLIC_DEVELOPER_PORTAL_URL/slug
// https://support.mallnline.com/slug   → $PUBLIC_SUPPORT_CENTER_URL/slug
// https://mallnline.com/slug           → $PUBLIC_MAIN_APP_URL/slug

This means markdown authors can write natural, readable links using production URLs, and the build pipeline ensures they resolve correctly in any environment.

Related

• Local Development Environment — Full-stack Podman setup including Make targets
• Informational Pages — The frontend's public-facing About, Help, For Business pages that link to these portals
• Beta Readiness Checklist — Launch checklist including documentation completeness
• Corporate Identity — Design system and terminology standards used across all portals