ᚦ Architecture Overview

Yggdrasil is BrierStudios' development framework, organized around the metaphor of the Norse world tree. This isn't just flavor — the Nine Realms model provides a genuine organizational structure that maps project types to workflows, conventions, and deployment pipelines.

Why Norse Mythology?

Because naming things is hard, and mythology gives us a shared vocabulary. When someone says "this belongs in Muspelheim," every team member immediately understands:

• It's experimental (ᛏ)
• It may break at any time
• It will be promoted to a proper realm when stable
• It follows relaxed conventions

The metaphor creates semantic compression — one word encodes an entire set of expectations.

The World Tree Model

                Asgard (Core)
                    |
        ┌───────────┼───────────┐
        |           |           |
    Vanaheim     Alfheim    Svartalfheim
    (Agents)    (UI)        (Docs)
        |           |           |
        └───────────┼───────────┘
                    |
                Midgard (Apps)
                    |
        ┌───────────┼───────────┐
        |           |           |
    Muspelheim   Niflheim    Jotunheim
    (Active)    (Assets)    (Massive)
                    |
                Helheim (Archive)

Each realm connects through the central trunk (Midgard) — the realm of human-facing applications. Everything ultimately serves the user.

Core Principles

1. Realm-Colocated Code

Code lives where it belongs, not in a monorepo free-for-all. Each realm has its own:

• Repository structure
• CI/CD pipeline
• Access controls
• Deployment targets
• Conventions file (REGLAS_YGGDRASIL.md)

2. Convention Enforcement

Every realm has a REGLAS_YGGDRASIL.md file that defines:

• Naming conventions (files, variables, commits)
• Branch strategies
• Required tests and coverage
• Deployment rules
• Code review requirements

These conventions are enforced by the Yggdrasil CLI (yg lint --realm-check) and cannot be bypassed in CI.

3. Directional Dependencies

Dependencies between realms follow a directional rule:

• Lower realms (closer to Helheim) can depend on higher realms (closer to Asgard)
• Never the reverse — Midgard apps should never be imported by Asgard core

Asgard ← Vanaheim ← Alfheim ← Midgard → Jotunheim → Helheim
        ← Svartalfheim ←               → Niflheim →
                              Muspelheim (isolated)

This prevents circular dependencies and keeps the architecture flowing downward.

4. Promotion Pipeline

Projects flow through realms as they mature:

Muspelheim (experiment) → Appropriate Realm (stable) → Jotunheim (scaled) → Helheim (retired)

Promotion is explicit — it requires a yg realms migrate command and an Architecture Decision Record.

Repository Structure

Each realm has a standardized repository structure:

<project>/
├── REGLAS_YGGDRASIL.md    # Realm-specific conventions
├── .yggdrasil.yml          # Project manifest
├── src/                    # Source code
├── tests/                  # Test suite
├── docs/                   # Project documentation
├── assets/                 # Static assets (symlink to Niflheim if large)
└── deploy/                 # Deployment configurations

The .yggdrasil.yml Manifest

.yggdrasil.yml

realm: vanaheim
name: lilith-discord
version: "2.0.0"
description: "Lilith v2.0 Discord bot"
dependencies:
  - yggdrasil-core@^6.0.0
  - personality-engine@^2.0.0
agents:
  - discord-bot
  - personality-profile:lilith
conventions:
  enforce: true
  auto-format: true
  test-coverage: 80
deploy:
  realm: vanaheim
  env: production
  platform: cloudflare-workers

Technology Stack

Layer	Technology	Purpose
Runtime	Node.js 20+ / Bun	Core execution
Framework	Custom (Yggdrasil Core)	Application framework
AI	OpenAI / Local Models	Agent intelligence
Frontend	React + Neon UI	Web interfaces
Docs	Docusaurus	Documentation (this site)
CI/CD	GitHub Actions	Automation
Deploy	Cloudflare Workers/Pages	Hosting
Storage	Cloudflare R2 / S3	Asset storage

Inter-Realm Communication

Realms communicate through a message bus powered by the Yggdrasil Core:

import { YggdrasilBus } from '@brierstudios/yggdrasil-core';

const bus = new YggdrasilBus();

// Asgard publishes a config update
bus.publish('asgard:config:updated', { realm: 'vanaheim', key: 'rate-limit', value: 100 });

// Vanaheim subscribes to config changes
bus.subscribe('asgard:config:updated', (event) => {
  applyConfigUpdate(event.data);
});

This event-driven architecture keeps realms loosely coupled while maintaining real-time coordination.

---

The roots run deep. The branches reach far. The tree endures. ᛜ