TenkaCloud Docs
← Home
日本語 English

Developer manual Stable

Use this manual when you change the TenkaCloud platform, its infrastructure code, shared packages, portals, or repository tooling. Deploying an event without changing platform code is an organizer task.

Your goal

Make one focused, reviewable change that preserves the platform contracts and passes the relevant repository checks.

Prepare the repository

bun install
git submodule update --init problems
make doctor

make doctor reports missing local prerequisites without installing or changing them. Use Getting started only for the runtime path you need.

Find the owner before editing

Path Responsibility
apps/ Admin, participant, and developer web applications
infrastructure/ AWS CDK stacks, environment configuration, deploy workflows
packages/ Shared contracts, SDKs, runtime adapters, and CLI code
scripts/ Repository checks, deploy helpers, and generated artifacts
problems/ Pinned official problem catalog submodule

Read the nearest tests and repository instructions before changing a contract. The platform architecture explains the plane boundaries and cross-plane events.

Change workflow

  1. Start from a GitHub Issue with a testable completion condition.
  2. Identify the narrowest owning module and its existing tests.
  3. Change the implementation and user-facing documentation together.
  4. Run focused tests while iterating.
  5. Run make harness and make before-commit before opening a pull request.
  6. Inspect the final diff and stage only the intended files.

Do not commit .env, credentials, generated secrets, or unrelated changes. Green unit tests do not prove a live AWS deploy or browser flow; report those verification boundaries honestly.

Code change or environment setting?

  • If an organizer only needs a different supported value, document and use the existing .env parameter. See the organizer manual.
  • If the accepted values, validation, synthesized resources, or runtime behavior must change, update the owning code, tests, .env.example, and manuals in the same pull request.
  • A database backend change must preserve the explicit data-migration and rollback boundary. Do not introduce silent dual writes.

MCP 2026-07-28

The TenkaCloud Always-On control plane exposes sessionless MCP 2026-07-28 endpoints. MCP is a common format through which an AI client calls an explicitly allowed TenkaCloud capability. The developer endpoint exposes only plain-language concept help and the recognized runtime list.

Connect to {ALWAYS_ON_CONTROL_PLANE_ORIGIN}/mcp/developer. The client must call server/discover first and send all of the following on each request:

  • MCP-Protocol-Version: 2026-07-28
  • Mcp-Method equal to the JSON body method
  • Mcp-Name equal to the target of tools/call or resources/read
  • protocol version, client info, and client capabilities in _meta

The endpoint does not use initialize, Mcp-Session-Id, or sticky routing. A legacy-only client cannot connect. Public list results carry a five-minute public cache hint; authenticated results carry a zero-duration private hint. A request body larger than 32 KiB is rejected before a tool runs.

Endpoint Boundary
/mcp/developer Public and read-only: explain_concept, list_runtime_capabilities
/mcp/problem-author Public and read-only: pure validation of supplied JSON
/mcp/organizer Existing middleware verifies the Auth0 issuer, audience, organization, tenant, and role
/mcp/participant Team-key authentication fixes the request to one team ID and event ID

When the organizer endpoint returns 401 Unauthorized, follow the resource_metadata link in WWW-Authenticate to discover the protected resource. The current Auth0 setup uses an OAuth client registered in advance by an administrator. TenkaCloud does not expose Dynamic Client Registration (DCR); use a Client ID Metadata Document (CIMD) only when the configured authorization server explicitly advertises client_id_metadata_document_supported.

Deploy, teardown, and setting changes are not synchronous MCP tools. A future mutation must use the Tasks extension for a durable handle, cancellation, and idempotency, and use a multi-round-trip request for explicit confirmation. Until then, use the existing UI and operating procedures.

The MCP host must show the tool name and arguments and obtain your approval before every tool call. All current tools advertise read-only, non-destructive, and idempotent annotations, but the HTTP server cannot prove that a remote client displayed its local approval screen. Do not connect a client that calls tools without this confirmation step.

apps/always-on-control-plane owns the serving implementation and packages/problem-sdk owns the problem-validation contract. Negative tests cover protocol headers, cross-role authentication mix-ups, and leakage of another tenant, team, flag, or credential.

Before requesting review

  • The new behavior has a focused test.
  • User-facing English and Japanese text agree.
  • Generated artifacts and indexes are up to date.
  • Links, types, formatting, and relevant builds pass.
  • Live checks that were not run are stated as Not run.
  • The Issue and pull request explain the user impact, not only the code diff.

Problem content belongs in a pack. If that is your task, use the problem author manual instead.