power-manage-server

Architecture

Three Go services sharing a Postgres event store and a Valkey/Redis task queue. Only the control server writes to Postgres. The gateway is stateless (no DB, no credentials). The indexer is read-only.

Data flow

Browser → [JWT] → Control → [AppendEvent] → Postgres
                                  ↓
Control → [enqueue Asynq task] → Valkey → [dequeue] → Gateway → [mTLS stream] → Agent
Agent → [stream result] → Gateway → [InternalService proxy] → Control → [AppendEvent] → Postgres
Indexer → [read Postgres] → [FT.CREATE/SEARCH] → Valkey

RPC catalog

The ControlService exposes 164 RPCs. Every RPC handler in server/internal/api/ validates input at the boundary (proto interceptor) AND at the handler level, enforces authorization, and appends immutable events.

Authentication (7 RPCs)

TOTP / 2FA (6 RPCs)

SSO / Identity Providers (11 RPCs)

SCIM (3 RPCs)

Users (12 RPCs)

Devices (8 RPCs)

Tokens (5 RPCs)

Actions (8 RPCs)

Action Sets (10 RPCs)

Definitions (11 RPCs)

Device Groups (14 RPCs)

Assignments (7 RPCs)

Dispatch (10 RPCs)

Audit (1 RPC)

LUKS / Secrets (5 RPCs)

OSQuery / Inventory (4 RPCs)

Logs (2 RPCs)

Roles (7 RPCs)

User Groups (14 RPCs)

Compliance (9 RPCs)

Search (2 RPCs)

Settings (4 RPCs)

Terminal (4 RPCs)

Event type catalog

93 event types recorded in the events table. Each event type has a corresponding payload struct in internal/eventtypes/payloads/ that serves as the single source of truth for the JSON wire format. Postgres triggers project these into *_projection tables.

Auth events (6)

UserLoggedIn, UserCreatedWithRoles, UserPasswordChanged, RegistrationTokenConsumed, CertificateRenewed, TOTPSetupInitiated, TOTPBackupCodesRegenerated

User lifecycle events (9)

UserEmailChanged, UserProfileUpdated, UserLinuxUsernameChanged, UserSshKeyAdded, UserSshKeyRemoved, UserSshSettingsUpdated, UserProvisioningSettingsUpdated, UserSelectionChanged, UserSystemActionLinked

Role events (3)

RoleCreated, RoleUpdated, UserRoleAssigned, UserRoleRevoked, UserRoleChanged

User group events (6)

UserGroupCreated, UserGroupUpdated, UserGroupMemberAdded, UserGroupMemberRemoved, UserGroupRoleAssigned, UserGroupRoleRevoked, UserGroupQueryUpdated, UserGroupMaintenanceWindowSet

Identity provider events (3)

IdentityProviderCreated, IdentityProviderSCIMEnabled, IdentityProviderSCIMTokenRotated

Identity link events (2)

IdentityLinked, IdentityLinkLoginUpdated, IdentityUnlinked

Device events (5)

DeviceRegistered, DeviceSeen, DeviceHeartbeat, DeviceLabelSet, DeviceLabelRemoved, DeviceLabelsUpdated, DeviceSyncIntervalSet, DeviceCertRenewed

Device group events (7)

DeviceGroupCreated, DeviceGroupRenamed, DeviceGroupDescriptionUpdated, DeviceGroupQueryUpdated, DeviceGroupMemberAdded, DeviceGroupMemberRemoved, DeviceGroupSyncIntervalSet, DeviceGroupMaintenanceWindowSet

Token events (1)

TokenRenamed

Action events (4)

ActionCreated, ActionRenamed, ActionDescriptionUpdated, ActionParamsUpdated

Action set events (4)

ActionSetRenamed, ActionSetDescriptionUpdated, ActionSetMemberAdded, ActionSetMemberRemoved, ActionSetMemberReordered

Definition events (4)

DefinitionRenamed, DefinitionDescriptionUpdated, DefinitionMemberAdded, DefinitionMemberRemoved, DefinitionMemberReordered

Assignment events (3)

AssignmentCreated, AssignmentModeChanged, AssignmentSortOrderChanged, DeviceUserAssignment, DeviceGroupAssignment

Execution events (7)

ExecutionCreated, ExecutionScheduled, ExecutionDispatched, ExecutionTerminal, ExecutionReason, ExecutionFailedReason, ExecutionFailedCompensating, ExecutionTimedOut

Command output events (1)

CommandOutput, OutputChunk

LUKS events (4)

LuksKeyRotated, LuksDeviceKeyRevocationRequested, LuksDeviceKeyRevocationDispatched, LuksDeviceKeyRevoked, LuksDeviceKeyRevocationFailed

LPS events (1)

LpsPasswordRotated

Compliance events (6)

CompliancePolicyCreated, CompliancePolicyRenamed, CompliancePolicyDescriptionUpdated, CompliancePolicyRuleAdded, CompliancePolicyRuleRemoved, CompliancePolicyRuleUpdated

Terminal events (4)

TerminalSessionStarted, TerminalSessionStopped, TerminalSessionTerminated, TerminalAdminMembershipRevoked

Settings events (1)

ServerSettingUpdated

Security events (1)

SecurityAlert

Database schema

14 Goose migrations in server/internal/store/migrations/:

Projection tables

Each domain aggregate has a projection table with a corresponding *_projection naming convention. Go-side projector listeners (internal/projectors/) react to committed events for cross-cutting concerns.

Internal package map (detailed)

internal/api/ — Control server RPC handlers (52 files)

internal/store/ — Event store and persistence (57 files)

Remaining packages

Invariants

1. No context.Background() in request paths. Two known findings in background goroutines (terminal_revocation_listener.go:96, settings_handler.go:128) — queued for lifecycle-context injection fix.
2. Every proto field crossing a trust boundary carries @gotags validate tag.
3. Every handler validates at boundary (interceptor) + handler level.
4. Every .catch() logs at minimum debug level.
5. No secrets in log fields.
6. All crypto calls carry domain-separation info tags.
7. Every mutation has owner-scoped WHERE clause.
8. Non-owner access returns NotFound, never PermissionDenied.
9. Every state-changing RPC is audit-logged.
10. IDs are ULIDs. Never crypto.randomUUID().
11. Never math/rand for cryptographic purposes.
12. Generated code regenerated from source, never hand-edited.
13. Events are append-only. REVOKE on events table, trigger-enforced.
14. Postgres as single writer. Only the control server writes. Gateway and indexer are read-only or have no DB access.

ADR index

23 Architecture Decision Records in server/docs/adr/: