This repository contains the source for the Kessel documentation site. Kessel is a platform that provides a unified inventory of resources, their relationships, and their changes over time. It offers primitives for resource organization, sharing, entitlement, history tracking, and event publishing -- along with an opinionated RBAC and tenancy model via Kessel RBAC.
This site documents integration patterns, SDK usage, API references, and operational guides for teams building with or running Kessel.
- Astro 5 with Starlight documentation theme
- Tailwind CSS v4 via Vite plugin
- TypeScript in strict mode
- Zod for frontmatter schema validation
- starlight-openapi plugin (pulls the OpenAPI spec from inventory-api at build time)
- marked for Markdown rendering in custom components
# Install dependencies
npm install
# Start the dev server at localhost:4321
npm run dev
# Build for production (runs astro check && astro build, outputs to ./dist/)
npm run build
# Preview the production build locally
npm run previewsrc/
content/docs/ # Documentation pages (.md and .mdx)
building-with-kessel/ # How-to guides, concepts, reference, archive
contributing/ # SDK spec, client API reference, writing guide
running-kessel/ # Architecture, installation, monitoring
start-here/ # Getting started, understanding Kessel
components/ # Custom Astro components
examples/ # Code examples (Go, Python, TypeScript, Ruby, Java, Bash)
middleware/ # Starlight route middleware
schemas/ # Zod schemas for frontmatter validation
styles/ # Global CSS
docs/ # AI agent guidelines
public/ # Static assets (favicon)
astro.config.mjs # Astro and Starlight configuration
config-overlay.mjs # Fork/overlay hooks for internal documentation
This repository is designed to be forked for internal documentation. The config-overlay.mjs file provides hook functions to modify the Astro and Starlight configuration (e.g., adding sidebar entries for internal docs) without altering upstream files. See CONTRIBUTING.md for details.
| Resource | Description |
|---|---|
| CONTRIBUTING.md | Project structure, commands, writing documentation, and fork/overlay guidance |
| AGENTS.md | Onboarding context for AI agents: conventions, architecture, and pointers to detailed guidelines |
| docs/api-contracts-guidelines.md | API versioning, SDK conventions, protobuf structures, code example patterns |
| docs/security-guidelines.md | OAuth2, TLS, SpiceDB authorization, Kafka SASL auth |
| docs/integration-guidelines.md | Kessel architecture, resource reporting, outbox/CDC, Kafka consumers |
| docs/performance-guidelines.md | gRPC channel reuse, token caching, CDC monitoring, Kafka performance |
| docs/error-handling-guidelines.md | Language-specific gRPC error handling, retry patterns, TLS errors |
| docs/database-guidelines.md | Inventory DB schema, outbox table, Debezium CDC, Kafka event schemas |
See LICENSE.
