Skip to content

Documentation Navigation

Holistic guide to kast-system documentation. Follow the learning paths below based on your goals.

Get Started: Getting Started Core Concepts: Glossary Main README: ../README.md Development: Testing → TDD Commands

Documentation Map

┌─────────────────────────────────────────────────────────────┐
│                    ENTRY POINT                              │
├─────────────────────────────────────────────────────────────┤
│ README.md          → Architecture overview, quick start     │
│ GETTING_STARTED.md → Complete tutorial (zero to production) │
│ GLOSSARY.md        → Terminology reference                  │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                  CORE COMPONENTS                            │
├─────────────────────────────────────────────────────────────┤
│ SUMMON.md          → Workload deployment chart             │
│ KASTER.md          → Glyph orchestration                   │
│ LIBRARIAN.md       → ArgoCD Apps of Apps                   │
│ BOOKRACK.md        → Configuration management              │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│              ADVANCED INFRASTRUCTURE                        │
├─────────────────────────────────────────────────────────────┤
│ GLYPHS.md          → Glyph system overview                 │
│ GLYPH_DEVELOPMENT.md → Create new glyphs                   │
│ LEXICON.md         → Infrastructure discovery              │
│ VAULT.md           → Secrets management                    │
│ HIERARCHY_SYSTEMS.md → Configuration inheritance           │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                    TRINKETS                                 │
├─────────────────────────────────────────────────────────────┤
│ MICROSPELL.md      → Microservices pattern                 │
│ TAROT.md           → Workflow automation                   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│              DEVELOPMENT & TESTING                          │
├─────────────────────────────────────────────────────────────┤
│ TESTING.md         → TDD methodology, test architecture    │
│ TDD_COMMANDS.md    → Command reference                     │
│ EXAMPLES_INDEX.md  → All examples catalog                  │
│ CODING_STANDARDS.md → Code conventions (root)              │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                   REFERENCES                                │
├─────────────────────────────────────────────────────────────┤
│ GLYPHS_REFERENCE.md → All available glyphs                 │
│ applicationset-guide.md → ArgoCD ApplicationSets           │
│ applicationset-quick-reference.md → Quick cheat sheet      │
│ glyphs/*.md        → Individual glyph docs                 │
└─────────────────────────────────────────────────────────────┘

Learning Paths

Path 1: Deploy Your First App (30 minutes)

  1. Getting Started - Tutorial
  2. Bookrack - Configuration structure
  3. Summon - Workload chart basics

Path 2: Understand Architecture (1 hour)

  1. README.md - System overview
  2. Glossary - Key terminology
  3. Librarian - How deployment works
  4. Kaster - Glyph orchestration
  5. Hierarchy Systems - Configuration patterns

Path 3: Infrastructure Integration (2 hours)

  1. Glyphs - Infrastructure as code
  2. Lexicon - Service discovery
  3. Vault - Secrets management
  4. Glyphs Reference - Available integrations

Path 4: Development & Testing (2 hours)

  1. Testing - TDD workflow
  2. TDD Commands - Command reference
  3. Glyph Development - Create new glyphs
  4. Examples Index - Learn from examples

Path 5: Advanced Patterns (3 hours)

  1. Microspell - Microservice patterns
  2. Tarot - Workflow automation
  3. ApplicationSet Guide - ArgoCD patterns
  4. Hierarchy Systems - Advanced config

By Use Case

"I want to deploy a simple container"

→ Getting Started → Summon

"I need to integrate with Vault/Istio/Cert-Manager"

→ Glyphs → Kaster → Glyphs Reference

"I'm organizing multiple applications"

→ Bookrack → Librarian

"I want to develop and test new features"

→ Testing → TDD Commands

"I need to create a new glyph"

→ Glyph Development → Testing

"I'm setting up GitOps with ArgoCD"

→ Librarian → ApplicationSet Guide

Component Relationships

Data Flow: Configuration → Deployment

Bookrack (YAML files)
    ↓
Librarian (reads books)
    ↓
ArgoCD Applications (generated)
    ↓
Helm Charts (summon/kaster/trinkets)
    ↓
Kubernetes Resources (deployed)

Docs: Bookrack → Librarian → Summon/Kaster

Template Flow: Glyphs → Resources

Glyph Definition (YAML)
    ↓
Kaster (orchestrates)
    ↓
Glyph Template (invoked)
    ↓
Lexicon (queries infrastructure)
    ↓
K8s Resource (generated)

Docs: Glyphs → Kaster → Lexicon

Development Flow: TDD Cycle

Write Example (test)
    ↓
Run tdd-red (should fail)
    ↓
Implement Feature
    ↓
Run tdd-green (should pass)
    ↓
Refactor
    ↓
Run tdd-refactor (still pass)

Docs: Testing → TDD Commands

Cross-Cutting Concerns

Configuration Hierarchy

Appears in: Bookrack, Vault paths, Lexicon defaults Doc: Hierarchy Systems

Infrastructure Discovery

Used by: Glyphs, Vault, Istio, Cert-Manager Doc: Lexicon

Test-Driven Development

Applies to: All charts, glyphs, trinkets Doc: Testing

Documentation Principles

  1. Start simple: Getting Started → Core components → Advanced
  2. Learn by doing: Every doc includes examples
  3. Follow flows: Data flow, template flow, development flow
  4. Cross-reference: Related docs linked explicitly
  5. Stay current: Docs tested with real code

Quick Command Reference

# Get started
make test                    # Run tests
make help                    # Show all commands

# Development
make tdd-red                 # Write failing test
make tdd-green               # Implement feature
make tdd-refactor            # Improve code

# Testing
make test syntax glyph vault # Quick syntax check
make test all glyph         # Comprehensive glyph tests

See TDD Commands for complete reference.

Contributing to Documentation

  1. Keep it simple and human
  2. Include working examples
  3. Update cross-references
  4. Test all commands
  5. Follow TDD approach
  6. No marketing/fluff

See CODING_STANDARDS.md for conventions.