# Yggdrasil -- Architectural Knowledge Graph

This directory stores your project's **architectural knowledge** as a tree of connected Markdown files. Unlike code comments which describe *what* code does, Yggdrasil captures the *meaning between* files -- design decisions, constraints, dependencies, and business rules.

Inspired by [Yggdrasil](https://github.com/krzysztofdudek/Yggdrasil) by Krzysztof Dudek.

## How It Works

1. **Nodes** describe system components (modules, services, layers)
2. **Aspects** describe cross-cutting concerns that apply across multiple nodes
3. **Flows** describe end-to-end processes that span multiple nodes
4. Agents run `python3 yg-context.py <node-name>` before modifying code to get relevant architectural context

## Directory Structure

```
.yggdrasil/
  README.md          -- This file
  root.md            -- Top-level system description
  nodes/             -- One file per module/component
    example.md       -- Template for a node
  aspects/           -- Cross-cutting concerns
    example.md       -- Template for an aspect
  flows/             -- End-to-end processes
    example.md       -- Template for a flow
```

## Getting Started

1. Copy `nodes/example.md` to create a node for each major module in your project
2. Copy `aspects/example.md` for each cross-cutting concern (auth, logging, etc.)
3. Copy `flows/example.md` for each key user journey
4. Update `root.md` with your system overview
5. Agents will automatically consult the graph before making changes

## Keeping It Updated

- When you add a new module, add a node
- When you make an architectural decision, update the relevant node's constraints
- When dependencies change, update the node's `depends_on` list
- The graph does NOT need to be comprehensive on day one -- add nodes as you work on areas