Kocoder/obsidian
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

vault backup: 2026-02-26 21:47:14

Browse Source
This commit is contained in:
Konstantin Hintermayer
2026-02-26 21:47:14 +01:00
parent a3f98b7600
commit 682ccd774b
10 changed files with 2096 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

351
Test/EventKit/07 - Technical Requirements.md Normal file
View File

@@ -0,0 +1,351 @@
---
tags:
- eventkit
---
# Technical Requirements
## Purpose
Non-functional requirements, deployment model, API design, and infrastructure considerations for EventKit.
---
## Technology Stack
### Core Decisions
| Layer | Technology | Rationale |
| -------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| **Backend language** | **Go** | Fast compilation, single binary deployment, excellent concurrency, strong ecosystem for network services |
| **API protocol** | **ConnectRPC** (gRPC wrapper) | Type-safe, code-generated clients, supports gRPC, gRPC-Web, and Connect protocols — works in browsers natively |
| **API definition** | **Protocol Buffers (Protobuf)** | Schema-first API design, backward-compatible evolution, generates Go server stubs + TypeScript/JS clients |
| **Database** | **PostgreSQL 15+** | Robust, proven, excellent JSON support, full-text search, strong ecosystem |
| **Frontend** | TBD (React, Vue, Svelte, or SolidJS) | ConnectRPC generates typed client SDKs for any JS/TS framework |
| **File storage** | Local filesystem or S3-compatible | Configurable per deployment |
### Why ConnectRPC
[ConnectRPC](https://connectrpc.com/) wraps gRPC to provide **three protocols in one**:
| Protocol | Transport | Use Case |
| ------------ | ------------------------------------ | ---------------------------------------------------------- |
| **Connect** | HTTP/1.1 or HTTP/2, JSON or Protobuf | Browser clients (no proxy needed), simple `curl` debugging |
| **gRPC** | HTTP/2, Protobuf | Server-to-server, federation, high-performance clients |
| **gRPC-Web** | HTTP/1.1, Protobuf | Legacy browser support via Envoy/proxy |
This means:
- **Web browsers** call the same API using the Connect protocol (plain HTTP + JSON or Protobuf) — no Envoy proxy required
- **[[04 - Federation Architecture|Federation]]** between instances uses gRPC for efficient binary communication
- **Mobile apps** can use gRPC natively
- **One `.proto` definition** generates server code (Go), browser client (TypeScript), and mobile client code
### Project Structure (Proposed)
```
eventkit/
├── proto/ # Protobuf definitions
│ ├── eventkit/v1/
│ │ ├── inventory.proto
│ │ ├── planning.proto
│ │ ├── crm.proto
│ │ ├── scanning.proto
│ │ ├── federation.proto
│ │ └── common.proto # Shared types (UUID, timestamps, pagination)
│ └── buf.yaml # Buf schema registry config
├── cmd/
│ └── eventkit/
│ └── main.go # Application entrypoint
├── internal/
│ ├── server/ # ConnectRPC service implementations
│ ├── domain/ # Business logic (pure Go, no framework deps)
│ ├── store/ # Database access (PostgreSQL)
│ ├── federation/ # Federation protocol handler
│ └── scanner/ # Scanning workflow logic
├── gen/ # Generated code (protoc / buf)
│ ├── go/
│ └── ts/ # TypeScript client for frontend
├── web/ # Frontend application
├── migrations/ # SQL migrations
├── docker-compose.yml
├── Dockerfile
└── buf.gen.yaml # Code generation config
```
### Key Go Libraries
| Library | Purpose |
| ---------------------------------- | ------------------------------------------------------ |
| **connectrpc.com/connect** | ConnectRPC server and client |
| **buf.build/gen** | Protobuf code generation (replaces `protoc`) |
| **jackc/pgx** | PostgreSQL driver (high-performance, pure Go) |
| **golang-migrate/migrate** | Database migrations |
| **rs/zerolog** or **slog** | Structured logging (slog is stdlib in Go 1.21+) |
| **go-chi/chi** or **std net/http** | HTTP router (ConnectRPC mounts on standard `net/http`) |
| **prometheus/client_golang** | Metrics |
| **golang-jwt/jwt** | JWT authentication |
| **testcontainers-go** | Integration testing with real PostgreSQL |
---
## Deployment
### Self-Hosted (Primary Model)
Each company runs their own instance. The deployment should be **simple and reproducible**.
| Approach | Description |
| ---------------------- | -------------------------------------------------------------------- |
| **Docker Compose** | Recommended for single-server deployments — all services in one file |
| **Kubernetes / Helm** | For larger companies wanting HA, auto-scaling, or multi-node |
| **Single binary + DB** | Possible for minimal deployments — app server + PostgreSQL |
### Minimum Infrastructure
| Component | Requirement |
| ---------------------- | ----------------------------------------------------------- |
| **Application server** | Linux VPS, 2+ CPU, 4+ GB RAM |
| **Database** | PostgreSQL 15+ |
| **File storage** | Local filesystem or S3-compatible object storage |
| **Reverse proxy** | Nginx / Caddy / Traefik (TLS termination) |
| **Domain + TLS** | Required for federation (valid certificate needed for mTLS) |
### Docker Compose Example Structure
```yaml
services:
eventkit:
image: eventkit/server:latest
# Single Go binary — serves ConnectRPC API + static frontend
ports:
- "8080:8080" # Connect protocol (HTTP/1.1 + HTTP/2)
- "8081:8081" # gRPC (federation, native clients)
environment:
- DATABASE_URL=postgres://eventkit:secret@db:5432/eventkit?sslmode=disable
- FEDERATION_ENABLED=true
- INSTANCE_URL=https://inventory.company-a.com
- FEDERATION_GRPC_PORT=8081
volumes:
- ./data/uploads:/app/uploads
db:
image: postgres:15
environment:
- POSTGRES_USER=eventkit
- POSTGRES_PASSWORD=secret
- POSTGRES_DB=eventkit
volumes:
- ./data/postgres:/var/lib/postgresql/data
caddy:
image: caddy:latest
ports:
- "443:443"
- "80:80"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile
```
> [!NOTE]
> Go compiles to a **single static binary** — no runtime, no JVM, no interpreter. The `eventkit` container is typically < 30 MB. Background workers run as goroutines within the same process.
---
## API Design
### Protocol
| Decision | Choice |
| -------------------------- | -------------------------------------------------------------------------------- |
| **API protocol** | ConnectRPC (supports Connect, gRPC, and gRPC-Web protocols simultaneously) |
| **Schema language** | Protocol Buffers v3 (`.proto` files) |
| **Code generation** | `buf` CLI — generates Go server stubs + TypeScript clients |
| **Transport (browsers)** | Connect protocol over HTTP/1.1 or HTTP/2 (JSON or Protobuf encoding) |
| **Transport (federation)** | gRPC over HTTP/2 (Protobuf encoding) |
| **Authentication** | JWT tokens (local users) + mTLS (federation) |
| **Pagination** | Cursor-based using `page_token` / `next_page_token` pattern in Protobuf messages |
| **Rate limiting** | Per-user and per-federation-partner, implemented as ConnectRPC interceptors |
### Protobuf Service Definitions
All APIs are defined as Protobuf services. Example structure:
```protobuf
// proto/eventkit/v1/inventory.proto
syntax = "proto3";
package eventkit.v1;
service InventoryService {
rpc ListProducts(ListProductsRequest) returns (ListProductsResponse);
rpc GetProduct(GetProductRequest) returns (Product);
rpc CreateProduct(CreateProductRequest) returns (Product);
rpc UpdateProduct(UpdateProductRequest) returns (Product);
rpc DeleteProduct(DeleteProductRequest) returns (DeleteProductResponse);
rpc ListAssets(ListAssetsRequest) returns (ListAssetsResponse);
rpc GetAsset(GetAssetRequest) returns (Asset);
rpc CheckAvailability(CheckAvailabilityRequest) returns (CheckAvailabilityResponse);
}
```
### Service Map
| Protobuf Service | Package | Purpose |
| ------------------- | ------------- | ------------------------------------------------ |
| `InventoryService` | `eventkit.v1` | Products, assets, cases, locations, availability |
| `PlanningService` | `eventkit.v1` | Events, pull lists, scheduling |
| `CrewService` | `eventkit.v1` | Crew profiles, assignments, availability |
| `TransportService` | `eventkit.v1` | Vehicles, truck packs, dispatch |
| `CRMService` | `eventkit.v1` | Contacts, companies, deals, pipeline |
| `QuoteService` | `eventkit.v1` | Quote building, versioning, PDF generation |
| `ScanningService` | `eventkit.v1` | Check-in, check-out, stocktake, case packing |
| `FederationService` | `eventkit.v1` | Trust handshake, sub-hire, asset resolution |
| `AuthService` | `eventkit.v1` | Login, token refresh, user management |
| `ReportService` | `eventkit.v1` | Dashboards, analytics, data export |
### How Clients Connect
| Client | Protocol | Encoding | Notes |
| -------------------- | --------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Web browser** | Connect | JSON (dev) or Protobuf (prod) | No proxy needed — standard `fetch()` under the hood |
| **Mobile app** | gRPC | Protobuf | Native gRPC client libraries |
| **Federation** | gRPC | Protobuf | Instance-to-instance via mTLS |
| **CLI tool** | Connect or gRPC | Protobuf | For automation and scripting |
| **cURL / debugging** | Connect | JSON | `curl -X POST -H 'Content-Type: application/json' -d '{...}' https://host/eventkit.v1.InventoryService/ListProducts` |
### ConnectRPC Interceptors (Middleware)
| Interceptor | Purpose |
| ------------------- | ------------------------------------------------- |
| **Auth** | Validate JWT, extract user context |
| **Federation Auth** | Validate mTLS certificate, check trust level |
| **Rate Limiter** | Per-user and per-partner rate limiting |
| **Logger** | Structured request/response logging |
| **Recovery** | Panic recovery with error reporting |
| **Validator** | Protobuf message validation (e.g. `buf validate`) |
| **Metrics** | Prometheus request duration, error rates |
---
## Authentication & Authorisation
### Authentication Methods
| Method | Use Case |
| --------------------------- | -------------------------------------- |
| **Email + password** | Default for local users |
| **OAuth 2.0 / OIDC** | SSO via Google, Microsoft, etc. |
| **LDAP / Active Directory** | Enterprise directory integration |
| **API keys** | For programmatic access / integrations |
| **mTLS** | Federation — instance-to-instance |
### Role-Based Access Control (RBAC)
| Role | Permissions |
| ------------- | -------------------------------------------------------------------- |
| **Admin** | Full system access, user management, federation management, settings |
| **Manager** | All operational features, reporting, approve quotes and purchases |
| **Planner** | Create/edit events, manage pull lists, assign crew |
| **Warehouse** | Scan in/out, manage stock, stocktakes, maintenance |
| **Sales** | CRM access, create/send quotes, manage pipeline |
| **Crew** | View assigned events, update availability, timesheets |
| **Read-only** | View dashboards and reports, no edit capabilities |
Custom roles with granular permission sets should also be possible.
---
## Data Model Highlights
### Key Relationships
```mermaid
erDiagram
COMPANY ||--o{ CONTACT : has
COMPANY ||--o{ DEAL : has
DEAL ||--o{ QUOTE : has
DEAL ||--o| EVENT : creates
EVENT ||--o{ PULL_LIST_ITEM : has
EVENT ||--o{ CREW_ASSIGNMENT : has
EVENT ||--o{ LOAD : has
EVENT }o--|| VENUE : at
EVENT }o--o| PROJECT : part_of
PRODUCT ||--o{ ASSET : has_instances
PRODUCT ||--o{ PULL_LIST_ITEM : referenced_by
ASSET }o--o| CASE : packed_in
ASSET }o--|| LOCATION : stored_at
ASSET ||--o{ ASSET_STATUS_LOG : has
ASSET ||--o{ MAINTENANCE_RECORD : has
CASE }o--|| LOCATION : stored_at
CASE ||--o{ ASSET : contains
KIT ||--o{ KIT_ITEM : contains
KIT_ITEM }o--|| PRODUCT : references
```
---
## Performance Requirements
| Metric | Target |
| --------------------- | ------------------------------------ |
| **Page load time** | < 2 seconds |
| **API response time** | < 500ms (p95) |
| **Search response** | < 1 second |
| **Scan processing** | < 500ms (perceived instant) |
| **Concurrent users** | 50+ per instance |
| **Asset count** | Support 100,000+ assets per instance |
| **Event count** | Support 10,000+ events per instance |
---
## Backup & Recovery
| Feature | Description |
| ------------------------- | -------------------------------------------------- |
| **Automated backups** | Daily database backups with configurable retention |
| **Point-in-time restore** | Transaction log backups for precise recovery |
| **File backup** | Uploaded files backed up alongside database |
| **Export** | Full data export in standard formats (JSON, CSV) |
| **Import** | Data import for migration from other systems |
---
## Monitoring & Observability
| Feature | Description |
| ------------------------- | ------------------------------------------------------ |
| **Health check endpoint** | `/health` for uptime monitoring |
| **Structured logging** | JSON logs for easy parsing and analysis |
| **Metrics** | Prometheus-compatible metrics endpoint |
| **Error tracking** | Integration with Sentry or similar |
| **Federation health** | Monitor federation connection status with each partner |
---
## Internationalisation
| Feature | Description |
| ----------------------- | -------------------------------------------------------- |
| **Multi-language UI** | Support for multiple interface languages |
| **Multi-currency** | Prices and costs in different currencies with conversion |
| **Timezone support** | Per-user timezone, event times stored in UTC |
| **Date/number formats** | Locale-aware formatting |
| **Right-to-left** | RTL layout support for applicable languages |
---
## Related Documentation
- [[00 - System Overview]] — High-level system overview
- [[01 - Inventory Management]] — Inventory module served by `InventoryService`
- [[02 - Planning Module]] — Planning module served by `PlanningService`
- [[03 - CRM Module]] — CRM module served by `CRMService` and `QuoteService`
- [[04 - Federation Architecture]] — Federation deployment and security
- [[05 - Barcode and QR Scanning]] — Hardware requirements and `ScanningService`
- [[06 - Module Integration]] — Cross-module workflows
- [[08 - Open Questions]] — Remaining technical decisions