# ase-docs

![Markdown](https://img.shields.io/badge/Markdown-documentation-blue.svg)
![Status](https://img.shields.io/badge/status-active-green.svg)

ASE Documentation - Architecture, design decisions, and development guidelines for ASE.

## Overview

`ase-docs` is the central documentation repository for the Antares Simulation Engine (ASE). It contains 345+ markdown documents organized into three top-level tiers:

- **servers/** - C++ backend: ECS architecture, modules, plugins, hub, scheduling, codegen
- **clients/** - Web client: React/Three.js, gate, preloader, audio, shaders, docs viewer
- **services/** - Microservices: authentication, future services

## Structure

```
ase-docs/
├── servers/                         # C++ Backend Documentation
│   ├── architecture/                # System design (22 subcategories)
│   │   ├── ARCH_ASE.md             # Main architecture overview
│   │   ├── calendar/               # Calendar system
│   │   ├── celestial/              # Celestial bodies
│   │   ├── codegen/                # Code generation pipeline
│   │   ├── eco/                    # Ecosystem (genetics, cycles)
│   │   ├── ephemeris/              # Ephemeris calculations
│   │   ├── hub/                    # Hub broadcast architecture
│   │   ├── network/                # WebRTC DataChannel
│   │   ├── schedule/               # 66 schedules in 21 tiers
│   │   ├── sky/                    # Sky rendering
│   │   ├── time/                   # Time system
│   │   ├── validator/              # ECS compliance validator
│   │   └── ...                     # + ai, genetics, logging, modules, plugin, render, replication, server, web
│   ├── instructions/                # Development guidelines (16 subcategories)
│   │   ├── ecs/                    # ECS rules (MUST READ!)
│   │   ├── build/                  # Build system
│   │   ├── create/                 # Module creation
│   │   ├── debug/                  # Debugging
│   │   ├── lint/                   # Linting rules
│   │   ├── markdown/               # Documentation style
│   │   ├── scripts/                # Script documentation
│   │   ├── validator/              # Validator usage
│   │   └── ...                     # + bdi, combat, compliance, gis, homeo, icons, logging, modules, workflow
│   ├── plans/                       # Implementation plans (30 subcategories)
│   ├── causality/                   # Causal chain documentation (25 subcategories)
│   ├── workflows/                   # Development workflows
│   ├── migrations/                  # System migrations (10 subcategories)
│   ├── reference/                   # Reference materials
│   ├── flows/                       # Data flow diagrams
│   ├── guidelines/                  # AI and development guidelines
│   ├── tests/                       # Test specifications
│   ├── concepts/                    # Core design concepts
│   ├── visions/                     # Long-term vision
│   ├── design/                      # Game design documents
│   ├── implements/                  # Implementation details
│   ├── devnotes/                    # Development notes
│   ├── hlog/                        # Historical decision log
│   ├── logging/                     # Log system docs
│   └── extern/                      # External references
│
├── clients/                         # Web Client Documentation
│   ├── architecture/                # Client architecture docs (ARCH_ASE_*)
│   │   ├── gate/                   # Gate (entry/auth screen)
│   │   ├── preloader/              # Preloader system
│   │   ├── audio/                  # Audio engine
│   │   ├── shader/                 # GLSL shaders
│   │   ├── landing/                # Landing page
│   │   ├── assets/                 # Asset management
│   │   ├── scripts/                # Build scripts
│   │   ├── codegen/                # Client codegen
│   │   ├── docviewer/              # Documentation viewer
│   │   └── splash/                 # Splash screen
│   └── web/                         # Web-specific docs (README files)
│       ├── gate/                   # Gate README
│       ├── preloader/              # Preloader README
│       ├── audio/                  # Audio README
│       └── ...                     # + shader, landing, assets, scripts, codegen, docviewer
│
├── services/                        # Microservice Documentation (future)
│
└── README.md
```

## Key Documents

### MUST READ for Developers

1. **servers/architecture/ARCH_ASE.md** - Overall architecture, 6-layer system
2. **servers/instructions/ecs/INST_ASE_ECS.md** - ECS rules (components, systems, anti-patterns)
3. **servers/architecture/schedule/ARCH_ASE_SCHEDULE.md** - 66 schedules in 21 tiers
4. **servers/guidelines/ai/GUIDE_ASE_AI_INSTRUCTIONS.md** - AI interaction rules
5. **CLAUDE.md** (repository root) - Quick reference for Claude Code

### For Web Client Development

1. **clients/architecture/gate/ARCH_ASE_GATE.md** - Gate authentication screen
2. **clients/architecture/preloader/ARCH_ASE_PRELOADER.md** - Preloader system
3. **clients/architecture/audio/ARCH_ASE_AUDIO.md** - Audio engine
4. **clients/architecture/shader/ARCH_ASE_SHADER.md** - GLSL shaders

### For Understanding the Architecture

1. **servers/architecture/hub/ARCH_ASE_HUB.md** - Hub broadcast architecture
2. **servers/architecture/codegen/ARCH_ASE_CODEGEN.md** - Code generation pipeline
3. **servers/architecture/network/ARCH_ASE_NETWORK.md** - WebRTC networking
4. **servers/workflows/WRFL_ASE_SYSTEM_SCHEDULING.md** - Schedule system reference

## Document Categories

| Prefix | Category | Description |
|--------|----------|-------------|
| ARCH | Architecture | System design and technical specifications |
| INST | Instructions | Development rules and guidelines |
| PLAN | Plans | Implementation plans and task breakdowns |
| CAUSA | Causality | Causal chain documentation (input/processing/output) |
| WRFL | Workflows | Development workflow documentation |
| MIG | Migrations | System migration guides |
| REF | Reference | Reference materials and lookup tables |
| FLOW | Flows | Data flow diagrams |
| GUIDE | Guidelines | AI and development guidelines |
| TEST | Tests | Test specifications |
| IMPL | Implements | Implementation details |
| DVN | Devnotes | Development session notes |
| HLOG | Historical Log | Decision records with rationale |

## Naming Convention

All documents follow: `{PREFIX}_ASE_{TOPIC}.md`

Examples:
- `ARCH_ASE_HUB.md` - Hub architecture
- `INST_ASE_ECS.md` - ECS instructions
- `PLAN_ASE_GENETICS.md` - Genetics implementation plan
- `CAUSA_ASE_EPHEMERIS.md` - Ephemeris causal chains

## Viewing Documentation

### In-Browser (ASE Docs Viewer)

Navigate to `https://antarien.com/ase/docs` for the built-in documentation viewer with:
- Hierarchical navigation with search
- Markdown rendering with syntax highlighting
- NerdFont icons and lifecycle state badges

### Locally

```bash
cd docs/ase-docs
# Browse the servers/ or clients/ tier
ls servers/architecture/
ls clients/architecture/
```

## Related Files

- **CLAUDE.md** (repository root) - Quick reference for AI assistant
- **README.md** (repository root) - Project overview

## License

Proprietary - Antares Simulation Engine