Where the code lives, how it builds, and how to start working on Semiont itself. Read this if you want to fix a bug, ship a feature, or understand the layered package design. For workflow conventions and the PR process, see CONTRIBUTING.md.
⚠️ Early development. Semiont is in active alpha. The API and package surface are not yet stable; breaking changes between 0.x releases are expected. External consumers should pin minor versions and read release notes before upgrading.
GitHub Codespaces (one-click, fastest):
See .devcontainer/README.md for what the prebuilt environment ships with.
Local checkout — clone the repo and follow LOCAL-DEVELOPMENT.md Path B (Building from Source). Path A in the same doc is for running an external KB project against published packages; Path B is the contributor workflow.
semiont/
├── specs/ # API specifications (spec-first architecture)
│ ├── src/ # OpenAPI source files (tracked in git)
│ │ ├── openapi.json # Root spec with $ref to all paths/schemas
│ │ ├── paths/ # Individual endpoint definitions
│ │ └── components/
│ │ └── schemas/ # Schema definitions
│ ├── openapi.json # Generated bundle (gitignored, built by Redocly)
│ └── docs/ # API and W3C annotation documentation
├── apps/ # Application packages
│ ├── frontend/ # Vite + React frontend SPA
│ ├── backend/ # Hono backend API server
│ └── cli/ # Semiont management CLI
├── packages/ # Shared workspace packages (see packages/README.md)
│ ├── core/ # OpenAPI types, branded IDs, event protocol
│ ├── api-client/ # HTTP transport adapter (HttpTransport, HttpContentTransport)
│ ├── sdk/ # SemiontClient, namespaces, session, flow state machines, worker adapters
│ ├── ontology/ # Entity types and tag schemas
│ ├── content/ # Content-addressed storage
│ ├── event-sourcing/ # Event store and materialized views
│ ├── graph/ # Graph database abstraction
│ ├── vectors/ # Vector storage, embeddings, semantic search
│ ├── inference/ # AI prompts, parsers, and text generation
│ ├── jobs/ # Job queue and worker infrastructure
│ ├── make-meaning/ # Context assembly, detection, reasoning
│ ├── react-ui/ # React components and hooks
│ ├── mcp-server/ # Model Context Protocol server
│ ├── observability/ # OpenTelemetry helpers (withSpan, traceparent, init)
│ └── test-utils/ # Testing utilities and mock factories
├── docs/ # System documentation
│ ├── development/ # Contributor-facing (this file, LOCAL-DEVELOPMENT, RELEASE, TESTING)
│ ├── administration/ # Operator-facing (deployment, security, observability, etc.)
│ ├── flows/ # The seven collaborative flows (yield, mark, match, …)
│ └── skills/ # Agent skill definitions for Claude Code and similar tools
└── scripts/ # Build and utility scripts
The layered architecture, dependency graph, and per-package summaries live in packages/README.md.
- CONTRIBUTING.md — branch/PR workflow, commit conventions, platform-contribution playbook.
- System Documentation — index for all system-architecture docs (actor model, knowledge system, container topology, package architecture).
- LOCAL-DEVELOPMENT.md — running locally; Path B for contributors building from source.
- TESTING.md — testing conventions and infrastructure.
- RELEASE.md — versioning and release process.
- packages/README.md — full package inventory with dependency graph.