Skip to content

Commit f4a1cfc

Browse files
evansimsevansims
committed
docs: update README
1 parent 48f878d commit f4a1cfc

File tree

1 file changed

+60
-101
lines changed

1 file changed

+60
-101
lines changed

‎README.md‎

Lines changed: 60 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -1,137 +1,108 @@
11
# InferaDB Management API
22

3-
**InferaDB control plane** — multi-tenant orchestration with headless APIs, Kubernetes-native deployment, and WebAuthn authentication.
3+
**Control plane** — multi-tenant orchestration with headless APIs, Kubernetes-native deployment, and WebAuthn authentication.
44

55
> [!IMPORTANT]
66
> Under active development. Not production-ready.
77
8-
## Features
9-
10-
- **Authentication**: Password, passkey, OAuth, email verification
11-
- **Multi-Tenancy**: Organization-based isolation with RBAC (Owner, Admin, Member)
12-
- **Vault Management**: Policy containers with team and user access grants
13-
- **Client Auth**: Backend service identity via Ed25519 certificates and JWT assertions
14-
- **Token Issuance**: Vault-scoped JWTs for Server API authorization
15-
168
## Quick Start
179

18-
See [docs/getting-started.md](docs/getting-started.md) for a complete tutorial.
19-
2010
```bash
21-
# Prerequisites: Rust 1.85+, Docker
22-
git clone https://github.com/inferadb/inferadb.git && cd inferadb/management
11+
git clone https://github.com/inferadb/management && cd management
2312
docker-compose up -d
2413
export INFERADB_MGMT__AUTH__KEY_ENCRYPTION_SECRET=$(openssl rand -base64 32)
2514
cargo run --bin inferadb-management
2615
```
2716

17+
Register a user:
18+
19+
```bash
20+
curl -X POST http://localhost:3000/v1/auth/register \
21+
-H "Content-Type: application/json" \
22+
-d '{"email": "alice@example.com", "password": "securepass123", "name": "Alice"}'
23+
```
24+
25+
Login:
26+
27+
```bash
28+
curl -X POST http://localhost:3000/v1/auth/login/password \
29+
-H "Content-Type: application/json" \
30+
-d '{"email": "alice@example.com", "password": "securepass123"}'
31+
```
32+
2833
| Endpoint | URL |
2934
| -------- | ------------------------------- |
3035
| REST API | `http://localhost:3000` |
3136
| gRPC API | `http://localhost:3001` |
3237
| Health | `http://localhost:3000/health` |
3338
| Metrics | `http://localhost:3000/metrics` |
34-
| OpenAPI | [openapi.yaml](openapi.yaml) |
39+
40+
## Features
41+
42+
| Feature | Description |
43+
| -------------------- | -------------------------------------------- |
44+
| **Authentication** | Password, passkey, OAuth, email verification |
45+
| **Multi-Tenancy** | Organization-based isolation with RBAC |
46+
| **Vault Management** | Policy containers with access grants |
47+
| **Client Auth** | Ed25519 certificates, JWT assertions |
48+
| **Token Issuance** | Vault-scoped JWTs for Server API |
3549

3650
## Architecture
3751

38-
```text
39-
inferadb-management # Binary
40-
├── inferadb-management-api # REST/gRPC handlers
41-
├── inferadb-management-core # Business logic, entities, repositories
42-
├── inferadb-management-storage # Storage backends (memory, FoundationDB)
43-
├── inferadb-management-grpc # Server API client
44-
├── inferadb-management-types # Shared type definitions
45-
└── inferadb-management-test-fixtures # Test utilities
52+
```mermaid
53+
graph TD
54+
API[inferadb-management-api] --> Core[inferadb-management-core]
55+
Core --> Storage[inferadb-management-storage]
56+
Storage --> FDB[(FoundationDB)]
57+
API --> GRPC[inferadb-management-grpc]
4658
```
4759

48-
**Storage**: Memory (dev/testing) or FoundationDB (production, distributed ACID)
60+
| Crate | Purpose |
61+
| --------------------------- | ------------------------ |
62+
| inferadb-management-api | REST/gRPC handlers |
63+
| inferadb-management-core | Business logic, entities |
64+
| inferadb-management-storage | Memory or FoundationDB |
65+
| inferadb-management-grpc | Server API client |
4966

50-
## Configuration
67+
## Key Concepts
68+
69+
| Entity | Description |
70+
| ------------ | --------------------------------------------- |
71+
| User | Account with auth methods (password, passkey) |
72+
| Organization | Workspace with members and roles |
73+
| Vault | Authorization policy container |
74+
| Client | Service identity with Ed25519 certs |
75+
| Team | Group-based vault access |
5176

52-
Via `config.yaml` or environment variables (`INFERADB_MGMT__` prefix):
77+
**Auth Flow:** User → Session → Vault access → JWT → Server API
78+
79+
## Configuration
5380

5481
```bash
5582
INFERADB_MGMT__STORAGE__BACKEND=foundationdb
5683
INFERADB_MGMT__STORAGE__FDB_CLUSTER_FILE=/etc/foundationdb/fdb.cluster
57-
INFERADB_MGMT__SERVER__HTTP_PORT=4000
58-
INFERADB_MGMT__OBSERVABILITY__LOG_LEVEL=debug
84+
INFERADB_MGMT__SERVER__HTTP_PORT=3000
85+
INFERADB_MGMT__AUTH__KEY_ENCRYPTION_SECRET=<base64>
5986
```
6087

6188
See [config.yaml](config.yaml) for all options.
6289

6390
## Development
6491

6592
```bash
66-
cargo test # All tests
67-
cargo test --package inferadb-management-core # Specific crate
68-
cargo clippy -- -D warnings # Lint
69-
cargo fmt # Format
70-
```
71-
72-
## Key Concepts
73-
74-
| Entity | Description |
75-
| ------------ | -------------------------------------------------- |
76-
| User | Account with auth methods (password, passkey) |
77-
| Organization | Multi-tenant workspace with members and roles |
78-
| Vault | Authorization policy container with access grants |
79-
| Client | Backend service identity with Ed25519 certificates |
80-
| Team | Group-based vault access |
81-
82-
**IDs**: Snowflake IDs (64-bit, globally unique, time-sortable)
83-
84-
**Auth Flow**: User authenticates → session token → request vault access → vault-scoped JWT → Server API
85-
86-
## API Examples
87-
88-
```bash
89-
# Register
90-
curl -X POST http://localhost:3000/v1/auth/register \
91-
-H "Content-Type: application/json" \
92-
-d '{"email": "user@example.com", "password": "securepass123", "name": "Alice"}'
93-
94-
# Login
95-
curl -X POST http://localhost:3000/v1/auth/login/password \
96-
-H "Content-Type: application/json" \
97-
-d '{"email": "user@example.com", "password": "securepass123"}'
98-
99-
# Create vault (authenticated)
100-
curl -X POST http://localhost:3000/v1/organizations/{org_id}/vaults \
101-
-H "Cookie: infera_session={session_id}" \
102-
-d '{"name": "Production Policies"}'
103-
104-
# Generate vault JWT
105-
curl -X POST http://localhost:3000/v1/organizations/{org_id}/vaults/{vault_id}/tokens \
106-
-H "Cookie: infera_session={session_id}"
93+
cargo test # All tests
94+
cargo clippy -- -D warnings # Lint
95+
cargo fmt # Format
10796
```
10897

109-
## Production
98+
## Deployment
11099

111100
```bash
112101
cargo build --release
113-
export INFERADB_MGMT__STORAGE__BACKEND=foundationdb
114-
export INFERADB_MGMT__AUTH__KEY_ENCRYPTION_SECRET=$(openssl rand -base64 32)
115102
./target/release/inferadb-management --config /etc/inferadb/config.yaml
116103
```
117104

118-
For Kubernetes deployment, see [docs/deployment.md](docs/deployment.md).
119-
120-
## Monitoring
121-
122-
- **Metrics**: Prometheus at `/metrics` (latency, status codes, auth attempts)
123-
- **Logs**: Structured JSON (production) or human-readable (dev)
124-
- **Tracing**: Optional OpenTelemetry integration
125-
- **Audit**: See [docs/audit-logs.md](docs/audit-logs.md)
126-
127-
## Load Testing
128-
129-
```bash
130-
brew install k6
131-
k6 run loadtests/auth.js
132-
```
133-
134-
See [loadtests/README.md](loadtests/README.md) and [docs/performance.md](docs/performance.md).
105+
See [docs/deployment.md](docs/deployment.md) for Kubernetes.
135106

136107
## Documentation
137108

@@ -140,20 +111,8 @@ See [loadtests/README.md](loadtests/README.md) and [docs/performance.md](docs/pe
140111
| Getting Started | [docs/getting-started.md](docs/getting-started.md) |
141112
| Authentication | [docs/authentication.md](docs/authentication.md) |
142113
| Architecture | [docs/architecture.md](docs/architecture.md) |
143-
| Data Flows | [docs/flows.md](docs/flows.md) |
144-
| Pagination | [docs/pagination.md](docs/pagination.md) |
145-
| Audit Logs | [docs/audit-logs.md](docs/audit-logs.md) |
146-
| Deployment | [docs/deployment.md](docs/deployment.md) |
147-
| Performance | [docs/performance.md](docs/performance.md) |
148-
| Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
149114
| API Reference | [openapi.yaml](openapi.yaml) |
150-
| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
151115

152116
## License
153117

154-
Business Source License 1.1. See [LICENSE.md](LICENSE.md).
155-
156-
## Support
157-
158-
- Issues: [github.com/inferadb/inferadb/issues](https://github.com/inferadb/inferadb/issues)
159-
- Security: [security@inferadb.com](mailto:security@inferadb.com)
118+
[Business Source License 1.1](LICENSE.md)

0 commit comments

Comments
 (0)