# Repository Structure

This document describes the folder organization for the Episteme (StemeDB) monorepo.

## Top-Level Directories

```
episteme/
├── .claude/              # Claude Code configuration (agents, guides, skills)
├── ai-lookup/            # AI-readable documentation and feature references
├── applications/         # End-user applications and tools
├── batteries/            # Pre-built integrations and batteries-included packages
├── community/            # Community Next.js app (research agent chat UI)
├── crates/               # Rust workspace crates (core database engine)
├── data/                 # Sample data and demo datasets
├── docs/                 # Human-readable documentation
├── latent/               # Python CLI tools (Latent Signal detection)
├── scripts/              # Build, deploy, and utility scripts
├── sdk/                  # Client SDKs (Go, potentially others)
├── uat/                  # User Acceptance Testing scenarios and results
└── use-cases/            # Vertical-specific use case documentation
```

## `/applications/` - End-User Applications

All standalone applications live here, regardless of language or framework.

| Directory | Description | Tech Stack |
|-----------|-------------|------------|
| `aphoria/` | Code-level truth linter powered by Episteme | Rust |
| `disputed/` | Web app for exploring claim conflicts | Next.js |
| `stemedb-dashboard/` | Admin dashboard for StemeDB | Next.js + shadcn/ui |

**Rules:**
- Each application has its own `package.json`, `Cargo.toml`, or equivalent
- Applications may depend on crates or SDKs from the monorepo
- Each application should have a `README.md` explaining its purpose

## `/crates/` - Rust Workspace Crates

The core database engine and supporting libraries.

| Crate | Purpose |
|-------|---------|
| `stemedb-core` | Assertion, LifecycleStage, types, signing utilities |
| `stemedb-wal` | Write-ahead log with crash recovery |
| `stemedb-storage` | KVStore, IndexStore, QuarantineStore |
| `stemedb-ingest` | Ingestion pipeline, signature verification |
| `stemedb-query` | Query engine, Materializer |
| `stemedb-lens` | Lenses (Recency, Consensus, Authority, etc.) |
| `stemedb-api` | HTTP API with axum |
| `stemedb-sim` | Simulation and testing |
| `stemedb-merkle` | BLAKE3 Merkle tree |
| `stemedb-rpc` | gRPC node-to-node communication |
| `stemedb-sync` | Merkle sync, gossip, anti-entropy |
| `stemedb-cluster` | SWIM membership, sharding, gateway |
| `stemedb-ontology` | Domain definitions, subject builders |
| `stemedb-chaos` | Chaos testing infrastructure |

## `/sdk/` - Client SDKs

| Directory | Language | Purpose |
|-----------|----------|---------|
| `sdk/go/steme` | Go | HTTP client with Ed25519 signing |
| `sdk/go/adk` | Go | ADK-Go tools for AI agents |

## `/docs/` - Documentation

| Directory | Purpose |
|-----------|---------|
| `docs/app-concepts/` | Application concept documents |
| `docs/data-structures.md` | Core data structure reference |
| `docs/demo/` | Demo scripts and materials |
| `docs/research/` | Research documents and design notes |
| `docs/runbooks/` | Operational runbooks (planned) |

## `/.claude/` - Claude Code Configuration

| Directory | Purpose |
|-----------|---------|
| `.claude/agents/` | Specialized agent definitions |
| `.claude/guides/` | Task-specific guidelines |
| `.claude/skills/` | Reusable skill documents |
| `.claude/commands/` | Slash command definitions |

## `/ai-lookup/` - AI-Readable Documentation

Quick reference documents optimized for AI assistants.

| File | Purpose |
|------|---------|
| `index.md` | Entry point and directory |
| `services/sdk.md` | SDK usage reference |
| `features/*.md` | Feature-specific documentation |
| `repo-structure.md` | This file |

## `/community/` - Community App

Next.js application for the research agent chat interface.
- Runs on port 18187
- Uses the Claim component for inline citation

## `/latent/` - Latent Signal

Python CLI tools for adverse event signal detection.
- Different coding rules from Rust crates
- Uses StemeDB as backend

## Naming Conventions

- **Crates:** `stemedb-{name}` (lowercase, hyphens)
- **Applications:** descriptive name (e.g., `disputed`, `aphoria`)
- **SDKs:** `sdk/{language}/{package}`
- **Docs:** lowercase with hyphens (e.g., `data-structures.md`)

## Port Allocations

| Port | Service |
|------|---------|
| 18180 | StemeDB HTTP API |
| 18181 | Cluster Gateway |
| 18182 | Cluster RPC |
| 18183 | SWIM Gossip |
| 18184 | Metrics (reserved) |
| 18185 | Admin (reserved) |
| 18186 | Latent Signal |
| 18187 | Community App |
| 18188 | Admin Dashboard |