Skip to content
LEF LEF Docs
GitHubLinkedIn

Editors

This page is for people who edit and maintain this documentation site.

Where things go

Section titled “Where things go”
SectionUse it for
/start/Entry points for new readers (what to read first).
/how-we-work/Norms, policies, and internal process (how we collaborate).
/architecture/Conceptual models (systems, environments, infrastructure).
/platforms-and-services/Platforms and service catalog docs (what it is + how to use it).
/run-and-support/Runbooks, procedures, and troubleshooting (how to operate).
/reference/Inventories and definition pages (facts, templates, lookup).

Example (DB connectivity): DB endpoints (model) → TCP proxy (service) → TCP proxy (facts) → Proxy & routing (operate) / SQL operations (operate).

Templates and repo rules

Section titled “Templates and repo rules”

Canonical templates

Use these as the starting point for new definition pages:

  • src/content/docs/reference/_templates/service.mdx
  • src/content/docs/reference/_templates/server.mdx
  • src/content/docs/reference/_templates/domain.mdx
  • src/content/docs/reference/_templates/environment.mdx

Repo rules (source of truth)

Editing rules for humans and AI agents live in:

AGENTS.md

Templates

Section titled “Templates”
service.mdx
---
title: "Template: Service definition"
description: "Canonical structure for documenting one service/application."
sidebar:
  hidden: true
pagefind: false
---

{/*
Purpose: Use this template for pages that document one service (an application, platform capability, or managed offering).
Rules:
- Do not invent facts. If you can’t confirm something, omit it.
- OPTIONAL sections/rows may be deleted entirely.
- Prefer removing unknown fields over leaving placeholders in committed pages.
*/}

## Overview (REQUIRED)
{/* Purpose: 1–3 sentences describing what the service is and who/what uses it. */}

## Purpose (OPTIONAL)
{/* Purpose: Short bullets describing what the service provides. */}

## Ownership & support (OPTIONAL)
{/* Purpose: Who maintains/operates the service and where requests/incidents go (only if explicitly documented). */}

## Entry points (OPTIONAL)
{/* Purpose: How users/systems access the service (URLs/hostnames, ports, protocols). No credentials. */}

## Where it runs (OPTIONAL)
{/* Purpose: Deployment location(s) for the service; link to server pages when explicitly known. */}

## Dependencies (OPTIONAL)
{/* Purpose: What this service depends on (DNS, databases, object storage, auth, upstream APIs). */}

## Data & persistence (OPTIONAL)
{/* Purpose: What data the service stores and where (only if confirmed). */}

## Access & security notes (OPTIONAL)
{/* Purpose: Confirmed access controls and auth mechanisms; link to policy pages where relevant. */}

## Operational notes (OPTIONAL)
{/* Purpose: Factual operator notes (configuration location, deploy/restart, routine maintenance). */}

## Monitoring & alerting (OPTIONAL)
{/* Purpose: Where to observe service health and what signals/alerts exist (only if confirmed). */}

## Backup & recovery (OPTIONAL)
{/* Purpose: Documented backup/restore behavior for the service’s data (only if confirmed). */}

## Known risks / failure modes (OPTIONAL)
{/* Purpose: Confirmed failure modes and symptoms; avoid speculative “best practices”. */}

## Runbooks (OPTIONAL)
{/* Purpose: Direct links to procedural docs for operating or recovering this service. */}

## Related (OPTIONAL)
{/* Purpose: Cross-links to adjacent docs; prefer Nova LinkButtons when used. */}

{/* TODO (only when needed):
- List missing info you intentionally omitted (e.g. ownership, monitoring, backups, runbooks).
*/}

Checks

Section titled “Checks”
  • Lint (all): npm run lint
  • Links only: npm run lint:links
  • Integrity (services/domains/DB routing): npm run lint:integrity
  • Lanes (environments tier integrity): npm run lint:lanes
  • Build: npm run build

Diagrams (PlantUML)

Section titled “Diagrams (PlantUML)”

Diagrams are written as PlantUML code fences:

thinkwise-environment.mdx
---
title: Thinkwise environment
description: System context and container model for a Thinkwise environment (stable across lanes).
sidebar:
  order: 20
---

import { LinkButton } from "starlight-theme-nova/components";

This page models the **Thinkwise environment** as a software system. Lanes (in [DTAP](/reference/glossary/dtap/)) are occurrences of the same system construct.

## System context

```plantuml
@startuml
!include <C4/C4_Context>
!NEW_C4_STYLE = 1
LAYOUT_TOP_DOWN()
HIDE_STEREOTYPE()
title Thinkwise environment — system context

Person(stakeholders, "Business stakeholders")
Person(delivery, "Solution architects & engineers")
Person(endUsers, "End users")
Person(ops, "LEF delivery/support")

System(twEnv, "Thinkwise Environment", "Lane instance (DTAP)")

System_Ext(entra, "Identity", "Microsoft Entra ID")
System_Ext(infra, "Shared infra enablers", "VPN, DNS, proxies, storage")
System_Ext(integrations, "External integrations")

Rel(stakeholders, twEnv, "Uses")
Rel(delivery, twEnv, "Uses")
Rel(endUsers, twEnv, "Uses")
Rel(ops, twEnv, "Uses")

Rel(twEnv, entra, "Uses")
Rel(twEnv, infra, "Uses")
Rel(twEnv, integrations, "Integrates with")
@enduml
```

{/* TODO: Link canonical integration/service pages for “external integrations” once available. */}

## Container model

Inside the Thinkwise environment boundary, we model the stable container set:

- **GUI** (web UI)
- **App/API runtime** (Indicium)
- **Database**
- **Object storage** (S3-compatible; avoid local disk as the source of truth)

```plantuml
@startuml
!include <C4/C4_Container>
!NEW_C4_STYLE = 1
LAYOUT_TOP_DOWN()
HIDE_STEREOTYPE()
title Thinkwise environment — container model

Person(user, "User")

System_Ext(reverseProxy, "Reverse proxy", "HTTP(S) ingress")
System_Ext(dns, "DNS", "Name resolution")
System_Ext(tcpProxy, "TCP proxy", "DB endpoints")
System_Ext(identity, "Identity", "Entra ID")

System_Boundary(twEnv, "Thinkwise Environment") {
  Container(gui, "GUI", "Web UI", "User-facing interface")
  Container(api, "App/API runtime", "Indicium", "Processing logic and APIs")
  ContainerDb(db, "Database", "SQL Server", "System state")
  ContainerDb(obj, "Object storage", "S3", "Files/objects")
}

Rel(user, reverseProxy, "Uses", "HTTPS")
Rel(reverseProxy, gui, "Routes", "HTTPS")
Rel(gui, api, "Calls", "HTTP(S)")
Rel(api, db, "Reads/writes", "SQL")
Rel(api, obj, "Stores/loads", "S3 API")

Rel(user, dns, "Resolves hostnames via")
Rel(api, tcpProxy, "Connects via", "SQL")
Rel(tcpProxy, db, "Routes", "SQL")
Rel(gui, identity, "Uses")
Rel(api, identity, "Uses")
@enduml
```

## Apply the aspect lens

<div class="sl-flex sl-flex-wrap sl-gap-2">
  <LinkButton href="/architecture/aspects/service/" variant="secondary">Service</LinkButton>
  <LinkButton href="/architecture/aspects/development/" variant="secondary">Development</LinkButton>
  <LinkButton href="/architecture/aspects/delivery/" variant="secondary">Delivery</LinkButton>
  <LinkButton href="/architecture/aspects/operational-management/" variant="secondary">Operational management</LinkButton>
  <LinkButton href="/architecture/aspects/security/" variant="secondary">Security</LinkButton>
</div>

## Where to go next

<div class="sl-flex sl-flex-wrap sl-gap-2">
  <LinkButton href="/architecture/archetypes/containers/" variant="secondary">Container archetypes</LinkButton>
  <LinkButton href="/reference/environments/" variant="secondary">Environment definitions (facts)</LinkButton>
  <LinkButton href="/run-and-support/infra/app-tiers/thinkwise/" variant="secondary">Indicium runtimes (operate)</LinkButton>
  <LinkButton href="/run-and-support/platforms/thinkwise/" variant="secondary">Thinkwise procedures (operate)</LinkButton>
  <LinkButton href="/platforms-and-services/platforms/thinkwise/" variant="secondary">Thinkwise platform docs</LinkButton>
</div>

{/* TODO:
- Capture “turn-key vs assisted vs support” responsibility boundaries once agreed (Architecture; no runbooks here).
*/}

Rendering is build-time:

  • Server renderer: set PLANTUML_SERVER_URL (recommended for CI and shared environments).
  • This repo includes the LEF root CA bundle at src/assets/lef_ca.pem. If you need a different CA, set PLANTUML_CA_CERT_PATH to a PEM bundle so Node can verify TLS.
  • Local renderer: set PLANTUML_JAR_PATH (and ensure Java is available; optionally set PLANTUML_JAVA_CMD).
  • Local dev without rendering: set PLANTUML_RENDER_MODE=skip.

Rendered diagrams include a Fullscreen button with zoom controls.

Integrity rules (enforced)

Section titled “Integrity rules (enforced)”
  • Service pages that are external/SaaS must set hosting: external in frontmatter.
  • *.db.lef backend routing is canonical in /reference/infra/proxy/tcp-proxy/; database endpoint pages must not duplicate backend host/port values.
  • Environment tier composition (GUI/app/DB) is canonical in src/data/lanes.mjs; environment pages must render it via <LaneStage /> and <LaneComponents />.