Build on Bosca

Everything you need to know to build features on the Bosca platform — from data models to GraphQL controllers, permissions, caching, and beyond.

This site is designed for both engineers and LLMs. The llms.txt endpoint provides machine-readable documentation for AI coding assistants.

Explore the Platform

Core/impl split, KSP code generation, and how the pieces fit together.

Data classes, @Repository, SQL mapping, and query patterns.

Business logic, @ServiceImplementation, injection, and lifecycle.

@TypeController, @Field, namespace pattern, queries, mutations, and batching.

HTTP endpoints, @RouteController, Route, APIRoute, SSERoute, and Pages.

Authentication, credentials, JWT token versioning, OAuth2, passkeys, and API tokens.

User identity, flexible attributes, visibility controls, and the Principal relationship.

Multi-tenant workspaces, membership, signup tokens, domain auto-join, and org permissions.

PermissibleEntity, evaluators, groups, visibility flags, and the full decision matrix.

Connection lifecycle, savepoints, deferred side effects, and GraphQL connections.

CacheManager, ServiceCache, RequestCache, two-tier architecture, and invalidation.

PubSubService, domain events, @JobEvent, dispatch, and job executors.

Batch mutations, permission filtering, transactional vs error-tolerant patterns.

Kotlin scripts: event triggers, API endpoints, AI agent tools, sandboxed execution.

Self-hosted Git server, pull requests, CI/CD, script & query source refs.

Content management, WorkOps, BX projects, Kubernetes, and MCP server.

Docker Compose, Kubernetes, downstream systems, and environment configuration.

Every annotation is processed by KSP at compile time — no runtime reflection.

@RepositoryJDBC implementation from interface SQL

@ServiceImplementationDI provider registration

@TypeControllerGraphQL resolver wiring

@RouteControllerHTTP route handler + DI provider

@JobDefinitionJob executor + enqueue helpers

@JobEventdispatch() for jobs + pub-sub

Adding a new feature (e.g., "Tags"):

Model — Create Tag and TagInput data classes in the core-* module.
Database migration — Create a Flyway migration SQL file.
Repository — Create TagRepository interface with @Repository and @Query.
Service interface — Create TagService in the core-* module.
Service impl — Create TagServiceImpl with @ServiceImplementation.
GraphQL schema — Create tags.graphqls under src/main/resources/graphql/.
Schema registration — Add @Schema("tags.graphqls") to the module's SchemaRegistrar.
Type controller — Create TagController implementing GraphQLController<Tag>.
Query controller — Create Tags object and TagsController.
Mutation controller — Create TagMutation object and TagMutationController.
Wire into the tree — Return namespace objects from parent controllers.
Events — Define @JobEvent-annotated event classes.
Jobs — Create @JobDefinition-annotated executors.