Help us improve
Share bugs, ideas, or general feedback.
From lfx-skills
Explains how LFX V2 platform components compose: Goa services, NATS, OpenFGA, OpenSearch, Heimdall, and deployment via Helm/ArgoCD. Use when tracing cross-service flows or classifying V2 service types.
npx claudepluginhub linuxfoundation/lfx-skills --plugin lfx-skillsHow this skill is triggered — by the user, by Claude, or both
Slash command
/lfx-skills:lfx-platform-architectureThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Cross-cutting architecture explainer for how the LFX V2 platform fits together.
Guides technical evaluation of code review feedback: read fully, restate for understanding, verify against codebase, respond with reasoning or pushback before implementing.
Share bugs, ideas, or general feedback.
Cross-cutting architecture explainer for how the LFX V2 platform fits together. Use this skill to understand component relationships, V2 service classes, and cross-repo ownership before handing implementation work to the owning repo.
Clean split:
/lfx-skills:lfx-platform-architecture: platform composition, V2 service
classes, cross-service responsibilities, and handoff points.<short-repo-name>-dev skill: Go coding conventions
such as generated-code boundaries, logging, errors, request context, tests,
formatting, and linting.If the task is about coding inside an individual V2 Go service, first route to
the owning repo. The repo-local path-scoped <short-repo-name>-dev skill should
attach on relevant Go/service paths, alongside the repo-owned top-level docs/
files named by that repo's CLAUDE.md.
The V2 platform is a Goa-on-NATS service mesh fronted by Heimdall, authorized by OpenFGA, indexed into OpenSearch, and read through query-service.
Browser
-> lfx-self-serve Angular SSR
-> lfx-self-serve Express BFF
|
v
Gateway API + Traefik
-> Heimdall (authn + openfga_check authz per route)
|
v
+----------------------+ +-------------------+ +-------------------+
| V2 Go services | | query-service | | access-check |
| (Goa + NATS/KV, | | (HTTP read API | | (HTTP wrapper |
| platform contracts) | | over OpenSearch) | | over fga-sync) |
+----------+-----------+ +---------+---------+ +---------+---------+
| | |
v v v
NATS subjects + KV OpenSearch index OpenFGA tuples
lfx.index.* -> indexer-service -> OpenSearch
lfx.fga-sync.* -> fga-sync -> OpenFGA
lfx.access_check.request -> fga-sync (cached check)
Auth and deployment sit alongside the data path:
lfx-v2-auth-service is the NATS RPC abstraction over Auth0 and Authelia
for identity, profile, and impersonation behavior.auth0-terraform owns Auth0 tenant configuration.lfx-v2-helm owns the shared platform chart and OpenFGA model template.lfx-v2-argocd owns deployed values, chart pins, image tags,
ApplicationSets, previews, and promotion.Classify before choosing a work plan. The class determines which responsibilities exist and which repo-local docs should be present.
| Class | Quick sense | Living examples |
|---|---|---|
| Native resource service | Owns its data in NATS JetStream KV and exposes full CRUD through a Goa API. | lfx-v2-project-service, lfx-v2-committee-service |
| Wrapper resource service | Exposes LFX V2 APIs while an external system remains the source of truth. | lfx-v2-voting-service, lfx-v2-meeting-service, lfx-v2-mailing-list-service, lfx-v2-survey-service |
| Supporting application service | Owns feature-specific behavior or state that is not a generic V2 resource contract. | lfx-v2-email-service, lfx-v2-newsletter-service |
| Proxy or consumer service | Thin HTTP or NATS facade over platform plumbing. Does not own a resource type. | lfx-v2-access-check, lfx-v2-auth-service, lfx-v2-persona-service |
| Platform service | Provides shared platform capability consumed by other services. | lfx-v2-indexer-service, lfx-v2-fga-sync, lfx-v2-query-service |
Living examples are examples, not central owners of implementation truth. Concrete behavior belongs in the repo that owns the code.
A native resource service owns resource state directly in NATS JetStream KV.
Typical responsibilities:
RuleSet entries for routes.Native local docs should identify owned KV buckets, request/reply subjects, indexed resource types, FGA object types, and any deviations from the usual CRUD, optimistic-locking, or health/readiness shape.
A wrapper resource service exposes an LFX V2 API while another system remains the source of truth.
Typical responsibilities:
Wrapper local docs should identify upstream ownership, LFX V2 to upstream field mappings, ID mapping requirements, local caches, emitted indexer/FGA messages, and upstream pagination, versioning, retry, or error quirks.
For ITX-specific plumbing such as OAuth2 M2M, lfx.lookup_v1_mapping, v1 KV
sync, and ITX_* environment variables, use
/lfx-skills:lfx-itx-integration.
Supporting application services own feature-specific behavior that participates in the platform but is not a generic resource service.
Typical responsibilities:
Examples:
lfx-v2-email-service owns transactional email request/reply and engagement
tracking. It does not render templates or publish indexer/FGA messages.lfx-v2-newsletter-service owns newsletter drafts, sent state, recipient
resolution orchestration, open tracking, and analytics. It consumes
query-service and email-service contracts.Proxy and consumer services do not own resource data and usually do not publish indexer or FGA messages.
Architecture expectations:
Examples:
lfx-v2-access-check owns the HTTP access-check API. FGA tuple semantics
live in lfx-v2-fga-sync.lfx-v2-auth-service owns auth/profile NATS RPCs. Auth0 tenant resources
live in auth0-terraform.lfx-v2-persona-service aggregates persona summaries. It does not own KV
resource state, indexer emission, or FGA emission.lfx-v2-indexer-service, lfx-v2-fga-sync, and lfx-v2-query-service own
platform contracts consumed by resource services.openfga_check
rules in the service chart.indexer-servicefga-syncindexer-service writes OpenSearch documents and emits domain events after
successful indexing.fga-sync writes or deletes OpenFGA tuples and updates its cache.Service-class responsibilities live in this skill. Go coding conventions live
in the owning service repo's path-scoped <short-repo-name>-dev skill.
query-service for indexed reads.query-service reads OpenSearch.query-service asks fga-sync for batched access checks over NATS.query-service removes unauthorized resources before returning results.Common failure owners:
indexer-service.fga-sync, or OpenFGA model.lfx.access_check.request.fga-sync checks its JetStream KV cache first.fga-sync calls OpenFGA and writes the result back to cache.The generic access-check and tuple contracts live in lfx-v2-fga-sync.
The HTTP wrapper over access checks lives in lfx-v2-access-check.
Adding or changing an OpenFGA type or relation touches multiple repos.
| Layer | Owner repo | File or surface |
|---|---|---|
| OpenFGA authorization model | lfx-v2-helm | charts/lfx-platform/templates/openfga/model.yaml |
| Endpoint authorization rules | Owning service repo | charts/<service>/templates/ruleset.yaml |
| Emitted access data | Owning service repo | service publisher code and local contract docs |
| Generic tuple handling and access checks | lfx-v2-fga-sync | handlers and docs/fga-sync-contract.md |
| Deployed values and promotion | lfx-v2-argocd | values, ApplicationSets, chart pins |
Coordination order:
lfx-v2-helm.lfx-v2-argocd if deployed values or chart pins are
part of the change.lfx-v2-fga-sync should not need type-specific code for a new resource type.
If it does, the envelope design is drifting.
| Concern | Owning repo |
|---|---|
| Product app, Angular SSR, Express BFF, shared package | lfx-self-serve |
| FGA tuple envelope, cache, access-check semantics | lfx-v2-fga-sync |
| Indexer envelope, OpenSearch document writes, indexing events | lfx-v2-indexer-service |
| Query API, OpenSearch read behavior, CEL, access filtering | lfx-v2-query-service |
| Access-check HTTP API | lfx-v2-access-check |
| Auth/profile/identity NATS RPC | lfx-v2-auth-service |
| Shared local platform chart and OpenFGA model | lfx-v2-helm |
| Deployed values, chart pins, image tags, ApplicationSets | lfx-v2-argocd |
| Local fixture loading and reset | lfx-v2-mockdata |
| Auth0 tenant control plane | auth0-terraform |
Use /lfx-skills:lfx and its repo map when deciding the primary repo for an
actual edit.
Read the owning repo before changing a contract shape. For exact current owner
files, use /lfx-skills:lfx and references/contract-ownership.md; this skill
keeps only the architectural ownership split.
| Concern | Owning repo |
|---|---|
| FGA envelope, tuple format, member operations, cache, access-check semantics | lfx-v2-fga-sync |
| Indexer envelope, OpenSearch document shape, event emission | lfx-v2-indexer-service |
| Query API, pagination over OpenSearch, filters, CEL, access filtering | lfx-v2-query-service |
| Cross-service Helm chart conventions | lfx-v2-helm |
| Shared platform chart and OpenFGA model | lfx-v2-helm |
| Deployed environment values, chart pins, image tags, ApplicationSets | lfx-v2-argocd |
lfx-v2-helm.lfx-v2-argocd.<short-repo-name>-dev
skills control coding conventions when Go or service files are edited.CLAUDE.md,
top-level docs/ contract files, and only use docs/agent-guidance/ where
the /lfx-skills:lfx repo map explicitly lists it as a transitional owner
path./lfx-skills:lfx-itx-integration.lfx-self-serve.After the platform flow and owners are clear, switch to the owning repo. The
owning repo's local instructions, top-level docs/ contract files, and
path-scoped <short-repo-name>-dev skill control implementation.