<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**

- [Explanations - Conceptual Understanding](#explanations---conceptual-understanding)
  - [Core Architecture](#core-architecture)
  - [Domain Knowledge](#domain-knowledge)
  - [Team & Collaboration](#team--collaboration)
  - [Important Limitations](#important-limitations)
  - [How to Use These Docs](#how-to-use-these-docs)
  - [Learning Progression](#learning-progression)
  - [Design Decision Context](#design-decision-context)
  - [Stuck or Curious?](#stuck-or-curious)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# Explanations - Conceptual Understanding

Background information and conceptual understanding. Explanations are **understanding-oriented** - they help you learn WHY things work the way they do, not HOW to do them.

## Core Architecture

Understand ggen's design and philosophy:

- **[Architecture](architecture.md)** - System design and components
- **[Ontology-Driven Development](ontology-driven.md)** - Semantic contracts and domain models
- **[Determinism](determinism.md)** - Reproducible, predictable code generation
- **[Code Projections](projections.md)** - How source ontologies map to multiple languages
- **[Marketplace Ecosystem](marketplace.md)** - Package ecosystem design

## Domain Knowledge

Deep dives into key concepts:

- **[Why RDF Matters](why-rdf-matters.md)** - Understanding the semantic web and RDF advantages
- **[SPARQL Design Philosophy](sparql-design-philosophy.md)** - Graph thinking vs relational thinking
- **[Type System Design](type-system-design.md)** - Zero-cost abstractions and compile-time guarantees
- **[Performance Characteristics](performance-characteristics.md)** - Understanding generation speed and scaling

## Team & Collaboration

How teams work with ggen:

- **[Collaboration Model](collaboration-model.md)** - Shared ontologies as team contracts
- **[Understanding Marketplace Maturity](marketplace-maturity.md)** - Package quality assessment

## Important Limitations

Understanding constraints:

- **[Limitations](limitations.md)** - When ggen isn't the right choice and anti-patterns to avoid

## How to Use These Docs

1. **Choose a concept** that interests or confuses you
2. **Read the full explanation** - These docs provide context and reasoning
3. **Understand the WHY** - Don't just learn the mechanism, understand the design
4. **Make informed decisions** - Use this knowledge when designing your projects
5. **Reference back** - Return to these docs when you encounter design questions

## Learning Progression

**Start with these if you're new:**
1. [Architecture](architecture.md) - Understand the overall system
2. [Ontology-Driven Development](ontology-driven.md) - Learn the mental model
3. [Why RDF Matters](why-rdf-matters.md) - Understand the semantic foundation

**Advanced topics:**
1. [Type System Design](type-system-design.md) - Zero-cost abstractions
2. [SPARQL Design Philosophy](sparql-design-philosophy.md) - Query language thinking
3. [Performance Characteristics](performance-characteristics.md) - Optimization insights

## Design Decision Context

Each explanation answers:
- **What is this concept?** - Clear definition
- **Why does ggen design it this way?** - Rationale and alternatives
- **What are the tradeoffs?** - Benefits and limitations
- **When should I use/avoid it?** - Practical guidance

## Stuck or Curious?

- 📖 **How-to Guides** - [Solve your specific problem](../how-to-guides/)
- 📚 **Tutorials** - [Learn by doing](../tutorials/)
- 📋 **Reference** - [Look up specific details](../reference/)
