Glossary

Audience

Everyone reading the docs.

Products

PLANA Pulse Platform — the infrastructure layer. Kubernetes, Crossplane, Envoy Gateway, Authentik. What this /platform/ section documents.

PLANA Business Cloud — the ERP product. Odoo Community + plana_* modules + Bulgarian fiscal pack + premium connectors. The user manual lives at /plana-business-cloud/. Customers call it "PLANA", not "Odoo".

BOS — the Business Operating System. The AI-first interface where customers chat with agents, see KPIs, and respond to alerts. User manual at /bos/.

PLANA Pulse — the AI-first layer between BOS and PLANA Business Cloud. Implemented by ai-agents (Python FastAPI) and surfaced through the BOS chat panel. Concept doc at /bos/what-is-plana-pulse.

Infrastructure

SKS — Exoscale's managed Kubernetes Service. Our cluster runs on SKS in zone bg-sof-1 (Sofia, Bulgaria).

pg01 — the PostgreSQL VM at pg01.planapulse.com (10.10.0.11). All tenant databases and most platform databases live here.

Envoy Gateway — the single ingress for the cluster. One Gateway resource (eg-gateway in plana-odoo), many HTTPRoutes attached.

Crossplane — the operator that turns composite resources (XRs) into concrete cluster objects. Replaces the previous saas-orchestrator.

PLANAClient — a Crossplane composite resource representing one customer tenant. Applying a PLANAClient creates the DB, HTTPRoute, backup CronJob, Matrix room, and the welcome event.

TenantUpgrade — a Crossplane CR that runs an upgrade against a tenant. strategy: same-major for code updates; strategy: snapshot-then-upgrade for cross-major (OpenUpgrade).

TemplateSnapshot — a Crossplane CR that produces a PostgreSQL TEMPLATE DB for fast tenant provisioning.

TenantEnvironment — a Crossplane CR representing a single Odoo environment. Most tenants have one. Pro+ customers can have multiple (prod + test) via separate TenantEnvironment resources under one PLANAClient.

EnvironmentRestore — a Crossplane CR that restores a tenant from a SOS backup, either in-place or as a side-by-side clone.

Flux — the GitOps reconciler. Watches infra/k8s/ on main and applies changes to the cluster every ~60 seconds.

SOPS — secrets-in-git tool. Encrypts YAML files with age. The single encrypted file is infra/secrets/plana-pulse.enc.yaml.

Vaultwarden — Bitwarden-compatible vault. The human-friendly mirror of SOPS at https://vault.planapulse.com.

Services

pulse-account — the customer-facing Nuxt 3 site at my.planapulse.ai. Login, dashboard, team, billing, integrations.

pulse-account-api — the Fastify backend behind pulse-account. Talks to tenant Odoos via XML-RPC; proxies banking and AI agent calls.

pulse-portal (a.k.a. BOS frontend) — the Vue 3 SPA at my.planapulse.ai/{workspace-slug}. The screen customers actually open to use BOS.

pulse-events — Fastify event bus over Redis Streams. CloudEvents 1.0 format. Stream PLANA:events.

pulse-banking — Fastify PSD2 connector. 10 Bulgarian bank adapters (Berlin Group).

pulse-billing — Stripe-backed subscription billing service.

pulse-notifications — sends transactional emails, in-app pushes.

pulse-data — Neural Business Network. pgvector-backed semantic memory for agents.

pulse-onboarding — the registration → first-tenant flow.

pulse-compliance — GDPR audit, 7-year retention service.

pulse-admin — internal staff panel at admin.planapulse.ai. VPN

• MFA required.

pulse-website — the marketing site at planapulse.ai. Vue 3 with vite-ssg (static).

pulse-website-api — backend for contact forms, newsletter, on the marketing site.

ai-agents — Python FastAPI service hosting the four BOS agents (Finance, Warehouse, Marketing, Sales).

Tenant naming

Subdomain — the customer-chosen identifier, e.g. acme. Lowercase, hyphen-allowed, ≤ 30 chars.

Project ID — integer ID from the ERP-side project.project.

Slug — same as subdomain. Used in customer-facing URLs.

Namespace — the Kubernetes namespace housing the tenant's workers. plana-odoo, plana-odoo-18, or plana-odoo-19 depending on the tenant's Odoo major.

Database name — equals the full hostname: {subdomain}.planapulse.app. Odoo's dbfilter=^%h$ ties the hostname to the DB.

Filestore path — /var/lib/odoo/filestore/{db-name} mounted via SubPath into the worker pod.

Domains

planapulse.ai — brand domain. my., admin., erp., and the marketing site.

planapulse.app — tenant Odoo hostnames. {subdomain}.planapulse.app.

planapulse.online — optional production alias for tenants.

planapulse.dev — test and preview tenants.

planapulse.com — internal backbone services (auth., git., vault., matrix., etc.).

plana.cloud — Mailu only. Do not touch from the SKS cluster.

Authentication

Authentik — our self-hosted identity provider. Staff SSO. Tenant users also authenticate through it via OIDC.

plana_auth — Odoo module on every tenant. Talks to Authentik via OIDC; implements the _login override and email-fallback linking.

TOTP — time-based one-time password (RFC 6238). The 6-digit code from an authenticator app. PLANA's second factor.

OIDC — OpenID Connect. The protocol Authentik uses to authenticate apps.

pa_token — the JWT cookie set by pulse-account-api after login. HS256, 15-min access, 30-day refresh.

pa_live_… — workspace API key. Created by tenant admins in BOS → Settings → API keys. bcrypt-hashed in the DB.

X-API-Key — header used for service-to-service authentication between PLANA-internal services.

Odoo / OCA

OCA — Odoo Community Association. The federation of community contributors maintaining the open Odoo module ecosystem.

OpenUpgrade — OCA's framework for migrating an Odoo database from one major version to the next. PLANA uses it via the two-pass strategy in cross-major TenantUpgrade.

plana_* — PLANA's own Odoo modules (e.g. plana_auth, plana_saas, plana_bus_redis). All start with plana_.

OpenUpgrade two-pass — the v17→v18 migration mechanism. Pass 1 runs under the source-version binary and installs the framework module; Pass 2 runs under the target-version binary and does --update=all.

Events and messaging

CloudEvents — the open spec for event envelope format. We use 1.0.

Redis Streams — the underlying storage for PLANA:events. We use MAXLEN ~50000 for retention.

SSE — Server-Sent Events. The streaming protocol used to push BOS chat tokens from ai-agents through pulse-account-api to the browser.

Operations

Soak — the post-cutover period during which a change is monitored but not yet trusted. Typical lengths: 48h for same-major changes, 5–7 days for cross-major or cross-cluster.

Insurance backup — a backup taken explicitly before a destructive operation, kept for at least 7 days regardless of the tier's normal retention.

Shadow Mode — the default agent runtime mode where write actions are simulated and logged but not executed.

Failure injection — controlled tests where infrastructure components are intentionally killed to verify recovery. Part of the stabilisation harness.

Bulgarian compliance

NPR — Bulgaria's National Revenue Agency export format. The monthly VAT submission file.

VIES — EU VAT Information Exchange System. Cross-border B2B VAT filing.

Intrastat — EU intra-community goods movement reporting.

CPDP — Commission for Personal Data Protection. Bulgaria's supervisory authority for GDPR.

QWAC — Qualified Website Authentication Certificate. Used for PSD2 mTLS handshake.

QSEALC — Qualified Electronic Seal Certificate. Used for PSD2 request signing.

TPP — Third-Party Provider. PLANA's role under PSD2 (specifically AISP — Account Information Service Provider).

AISP — Account Information Service Provider. The PSD2 role that reads accounts and transactions with consent. PLANA holds this.

PISP — Payment Initiation Service Provider. PLANA does NOT hold this role; we do not initiate payments.

Where to read more

• Naming conventions — the rules for new names
• API index — every API endpoint collated
• Repo map — what each of the 32 repos contains