Skip to content

Commit fc3211e

Browse files
evansimsevansims
committed
docs: update Overview
1 parent ca16eb7 commit fc3211e

File tree

1 file changed

+142
-3
lines changed

1 file changed

+142
-3
lines changed

‎docs/Overview.md‎

Lines changed: 142 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,119 @@
1-
# Management (Control Plane) API
1+
# Management API: Architecture & Entity Reference
22

3-
This system serves as the Control Plane for our system, allowing users to self-service and manage their own user accounts, organizations, groups, and vaults. It communicates (server-to-server) with our @server/ using gRPC for all data operations, and exposes gRPC and REST APIs for client connections. These client connections will be from a web-based Dashboard, CLI tools, and potentially other client types in the future.
3+
> **Developer Guide**: This document provides a comprehensive reference for the InferaDB Management API architecture, data model, and core entity definitions. Use this as your primary reference when implementing features or understanding system behavior.
44
5-
For data storage, we will support both in-memory and FoundationDB. In-memory is the default for development, and FoundationDB for production.
5+
## Overview
6+
7+
The **Management API** is InferaDB's control plane, providing self-service capabilities for users to manage their accounts, organizations, teams, vaults, and access control. It serves as the orchestration layer between client applications (Dashboard, CLI, SDKs) and the InferaDB Server (data plane).
8+
9+
**Key Responsibilities**:
10+
11+
- User authentication & session management (password, passkey/WebAuthn, OAuth)
12+
- Multi-tenant organization management with role-based access control (RBAC)
13+
- Vault lifecycle management (create, configure, sync with Server, delete)
14+
- Client credential management for backend services (Ed25519 certificates, OAuth 2.0 JWT Bearer)
15+
- Token issuance for Server API access (vault-scoped JWTs with refresh tokens)
16+
- Audit logging for security events and compliance
17+
18+
**Architecture**:
19+
20+
- **Storage**: FoundationDB (production) or in-memory (development)
21+
- **Server Communication**: gRPC for real-time vault synchronization
22+
- **Client APIs**: REST (Dashboard, CLI) and gRPC (SDKs)
23+
- **Deployment**: Single-instance (dev/small deployments) or multi-instance HA (production)
24+
25+
**Related Documentation**:
26+
27+
- [Architecture.md](Architecture.md) - System architecture diagrams and deployment topologies
28+
- [Flows.md](Flows.md) - Sequence diagrams for key operations (registration, login, token generation)
29+
- [Authentication.md](Authentication.md) - Complete authentication and authorization guide
30+
- [GettingStarted.md](GettingStarted.md) - Step-by-step setup tutorial
31+
- [OpenAPI Specification](../OpenAPI.yaml) - Complete REST API reference
32+
33+
---
34+
35+
## Table of Contents
36+
37+
### Foundation
38+
39+
- [Primary Keys](#primary-keys) - Snowflake ID generation and collision avoidance
40+
41+
### Core Entities
42+
43+
- [User Management](#user-management)
44+
45+
- [User](#user) - User accounts
46+
- [UserEmail](#useremail) - Email addresses and verification
47+
- [UserEmailVerificationToken](#useremailverificationtoken) - Email ownership verification
48+
- [UserPasswordResetToken](#userpasswordresettoken) - Password reset flow
49+
- [UserPasskey](#userpasskey) - WebAuthn/FIDO2 credentials
50+
- [UserSession](#usersession) - Authentication sessions
51+
- [SessionType](#sessiontype) - Session type enumeration
52+
53+
- [Organizations](#organizations)
54+
55+
- [Organization](#organization) - Tenant/organization entities
56+
- [OrganizationMember](#organizationmember) - User membership in organizations
57+
- [OrganizationRole](#organizationrole) - Member, Admin, Owner roles
58+
- [OrganizationInvitation](#organizationinvitation) - Invite users to join
59+
- [OrganizationTier](#organizationtier) - Billing tiers and limits
60+
61+
- [Teams](#teams)
62+
63+
- [OrganizationTeam](#organizationteam) - Groups of users within organizations
64+
- [OrganizationTeamMember](#organizationteammember) - Team membership
65+
- [OrganizationTeamPermission](#organizationteampermission) - Delegated permissions
66+
- [OrganizationPermission](#organizationpermission) - Permission enumeration
67+
68+
- [Clients](#clients)
69+
70+
- [Client](#client) - Service identities for backend applications
71+
- [ClientCertificate](#clientcertificate) - Ed25519 key pairs for JWT signing
72+
73+
- [Vaults](#vaults)
74+
75+
- [Vault](#vault) - Authorization policy containers
76+
- [VaultSyncStatus](#vaultsyncstatus) - Synchronization status with Server
77+
- [VaultTeamGrant](#vaultteamgrant) - Team-based vault access
78+
- [VaultUserGrant](#vaultusergrant) - Direct user vault access
79+
- [VaultRole](#vaultrole) - Reader, Writer, Manager, Admin roles
80+
81+
- [Tokens](#tokens)
82+
83+
- [VaultRefreshToken](#vaultrefreshtoken) - Long-lived refresh tokens for vault JWTs
84+
85+
- [Audit](#audit)
86+
- [AuditLog](#auditlog) - Security event logging
87+
- [AuditEventType](#auditeventtype) - Event type enumeration
88+
89+
### System Behavior
90+
91+
- [Behavioral Rules](#behavioral-rules) - Entity lifecycle and business logic
92+
- [Authentication & Authorization](#authentication--authorization) - Login flows and token management
93+
- [Email Flows](#email-flows) - Email verification and password reset
94+
95+
### System Design
96+
97+
- [API Design](#api-design) - REST conventions and best practices
98+
- [Management → Server Authentication](#management--server-privileged-authentication) - gRPC inter-service communication
99+
- [Server API Integration](#server-api-role-enforcement--tenant-isolation) - Role enforcement and tenant isolation
100+
- [Configuration](#configuration) - Environment variables and settings
101+
- [Multi-Instance Deployment](#multi-instance-deployment--distributed-coordination) - HA setup and leader election
102+
- [Multi-Tenancy & Data Isolation](#multi-tenancy--data-isolation) - Tenant separation guarantees
103+
- [Soft Delete & Cleanup](#soft-delete--cleanup) - Grace periods and background jobs
104+
105+
### Operations
106+
107+
- [Testing Strategy](#testing-strategy) - Test coverage and approaches
108+
- [Error Response Taxonomy](#error-response-taxonomy) - Standardized error codes
109+
- [Enhanced Security Features](#enhanced-security-features) - Rate limiting and security hardening
110+
- [Observability & Monitoring](#observability--monitoring-day-1) - Logging, metrics, and tracing
111+
112+
### Planning
113+
114+
- [Future Considerations](#future-considerations) - Roadmap and enhancement ideas
115+
116+
---
6117

7118
## Primary Keys
8119

@@ -60,8 +171,24 @@ let user_id = id_gen.next_id(); // Returns i64
60171

61172
**Storage**: IDs are stored as `i64` in FoundationDB and serialized as strings in JSON responses to avoid JavaScript's 53-bit integer precision limit.
62173

174+
---
175+
63176
## Entity Definitions
64177

178+
This section provides detailed specifications for all entities in the Management API data model. Each entity includes:
179+
180+
- **Purpose**: What the entity represents
181+
- **Data**: Field definitions with types, constraints, and validation rules
182+
- **Constraints**: Uniqueness requirements and business rules
183+
- **Cascade Delete**: Behavior when parent entities are deleted
184+
- **API Path**: REST endpoint location
185+
186+
> **Implementation Note**: All entities support soft deletion (90-day grace period) unless otherwise noted. See [Soft Delete & Cleanup](#soft-delete--cleanup) for details.
187+
188+
---
189+
190+
## User Management
191+
65192
### User
66193

67194
Represents an individual user. Lives under the `/v1/users` API path.
@@ -252,6 +379,8 @@ Enum defining session types (hard-coded).
252379

253380
---
254381

382+
## Organizations
383+
255384
### Organization
256385

257386
Represents a single organization (tenant). Lives under the `/v1/organizations` API path.
@@ -307,6 +436,8 @@ Associates a User with an Organization. Lives under the `/v1/organizations/:org/
307436

308437
---
309438

439+
## Clients
440+
310441
### Client
311442

312443
Represents a registered Client for an Organization using the Client Assertion pattern (OAuth 2.0 JWT Bearer, RFC 7523). A client is a logical service identity (e.g., "Production Backend", "CI/CD Pipeline") that can have multiple certificates for graceful rotation.
@@ -532,6 +663,8 @@ Enum defining Organization billing/feature tiers (hard-coded).
532663

533664
---
534665

666+
## Teams
667+
535668
### OrganizationTeam
536669

537670
Represents a team (group of users) within an Organization. Lives under the `/v1/organizations/:org/teams` API path.
@@ -718,6 +851,8 @@ Users can accumulate permissions from multiple sources:
718851

719852
---
720853

854+
## Vaults
855+
721856
### Vault
722857

723858
Represents an authorization vault (tenant in @server). Lives under the `/v1/vaults` API path.
@@ -840,6 +975,8 @@ Enum defining Vault access roles (hard-coded).
840975

841976
---
842977

978+
## Tokens
979+
843980
### VaultRefreshToken
844981

845982
Represents a refresh token for vault-scoped JWTs. Enables long-running operations and background jobs to refresh their Server API access tokens without re-authenticating. Not exposed via REST API (internal use only).
@@ -906,6 +1043,8 @@ Represents a refresh token for vault-scoped JWTs. Enables long-running operation
9061043

9071044
---
9081045

1046+
## Audit
1047+
9091048
### AuditLog
9101049

9111050
Represents a security audit event for tracking authentication events, permission changes, and sensitive operations. Not directly exposed via REST API (admin/debug access only via `/v1/audit-logs` endpoint).

0 commit comments

Comments
 (0)