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

vault backup: 2026-02-27 10:43:35

Browse Source
This commit is contained in:
Konstantin Hintermayer
2026-02-27 10:43:36 +01:00
parent cf4bb46286
commit dcfaa481bd
13 changed files with 1405 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
Test/EventKit/07 - Technical Requirements.md
View File

@@ -22,7 +22,10 @@ Non-functional requirements, deployment model, API design, and infrastructure co
| **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** | **React** (TanStack Router + TanStack Query) | Team expertise, strong ecosystem, ConnectRPC generates typed TS clients |
| **File storage** | Local filesystem or S3-compatible | Configurable per deployment |
| **UI components** | **shadcn/ui** | Accessible, composable, Tailwind-based component library |
| **File storage** | Local filesystem or S3-compatible | Configurable per deployment — local for self-hosted, S3/MinIO for SaaS |
| **Search** | PostgreSQL full-text search | Start with built-in FTS; add dedicated engine (Meilisearch) later if needed |
| **Background jobs** | NATS or Redis | External message broker — suits Kubernetes deployment model |
### Why ConnectRPC
@@ -48,8 +51,10 @@ This means:
| **Framework** | React | SPA — SEO is not a requirement |
| **Routing** | @tanstack/router | Type-safe, file-based routing |
| **Data fetching** | @tanstack/query | Caching, background refetching, optimistic updates |
| **UI components** | shadcn/ui | Accessible, composable component library |
| **API client** | ConnectRPC generated TS code | Type-safe from `.proto` definitions |
| **Build tool** | Vite | Fast dev server and optimised builds |
| **Theme** | Dark mode (default) | Light mode + high contrast mode as toggles |
### Mobile App
@@ -119,13 +124,17 @@ Each company runs their own instance. The deployment should be **simple and repr
For the hosted SaaS offering, use a **shared database with tenant isolation**:
| Aspect | Approach |
| -------------------- | ----------------------------------------------------------------------- |
| **Database** | Shared PostgreSQL instance, tenant ID on every table |
| **Isolation** | Row-level security (RLS) policies enforce tenant boundaries |
| **Connection** | Connection pooling shared across tenants |
| **Migration** | Single schema, all tenants upgrade together |
| **Data sovereignty** | Tenants wanting full isolation should use self-hosted or dedicated tier |
| Aspect | Approach |
| -------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Database** | Shared PostgreSQL instance, tenant ID on every table |
| **Isolation** | Row-level security (RLS) policies enforce tenant boundaries — complete isolation, no cross-tenant data ever |
| **Cross-tenant** | No shared data between tenants — use Federation for inter-company workflows |
| **Connection** | Connection pooling shared across tenants |
| **Migration** | Single schema, all tenants upgrade together |
| **Data sovereignty** | Tenants wanting full isolation should use self-hosted or dedicated tier |
| **Onboarding** | Self-service with admin approval, or manual admin creation |
| **Data export** | Full JSON/CSV export at any time (GDPR Article 20) + right to be forgotten |
| **Quotas** | Soft limits with warnings — pricing tiers TBD |
| Approach | Description |
| ---------------------- | -------------------------------------------------------------------- |
@@ -262,18 +271,24 @@ service InventoryService {
## Authentication & Authorisation
### Authentication Methods
### Identity Provider — Keycloak
| 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 |
Authentication is delegated to **Keycloak** as the central identity provider:
| Component | Approach |
| ---------------------- | ---------------------------------------------------------------------------------------------------- |
| **Identity provider** | Keycloak (self-hosted alongside EventKit) |
| **Protocol** | Generic OIDC — works with Keycloak, Auth0, or any OIDC provider |
| **Session management** | Handled by Keycloak (tokens, refresh, SSO) |
| **User onboarding** | Admin creates user → email invitation → user sets password |
| **Role management** | Roles defined in Keycloak, permissions mapped in EventKit |
| **Federation auth** | mTLS certificates for instance-to-instance communication |
| **API keys** | Granular scopes (e.g. `inventory:read`, `planning:write`) — start with full access, add scopes later |
### Role-Based Access Control (RBAC)
Roles are managed in Keycloak. EventKit reads roles and maps them to permissions:
| Role | Permissions |
| ------------- | -------------------------------------------------------------------- |
| **Admin** | Full system access, user management, federation management, settings |
@@ -284,7 +299,70 @@ service InventoryService {
| **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.
Custom roles with granular permission sets are fully supported — admins create roles in Keycloak, then map permissions in EventKit.
---
## Data Management
### Soft Delete
| Behaviour | Description |
| --------------- | ------------------------------------------------------- |
| **Default** | Soft delete — records marked as deleted, hidden from UI |
| **Recovery** | Admins can restore soft-deleted records |
| **Hard delete** | Admin action after configurable retention period |
| **Cascade** | Related records follow the parent's delete behaviour |
### Audit Trail
| Feature | Description |
| ------------------------ | --------------------------------------------- |
| **Field-level tracking** | Old value → new value for every field change |
| **User attribution** | Who made the change and when |
| **Entity history** | Full change history per record (like Git log) |
| **Immutable log** | Audit records cannot be edited or deleted |
| **Future** | Full diff view (Git-style) for every record |
### Caching
| Component | Strategy |
| ---------- | ----------------------------------------------------- |
| **Layer** | Redis (shared with background job broker) |
| **Scope** | Session cache, query cache, federation response cache |
| **Policy** | TTL-based with manual invalidation on writes |
### Database Migrations
| Environment | Strategy |
| --------------- | ---------------------------------------------------- |
| **Development** | Automatic on startup |
| **Production** | Explicit migration step before deploying new version |
---
## UI & Navigation
| Feature | Description |
| ------------------- | -------------------------------------------------------------------------------- |
| **Navigation** | Sidebar with module sections + command palette (Cmd+K) |
| **Dashboard** | Configurable per user — multiple layouts with simple view switching |
| **Bulk operations** | Bulk status change, assign to event, print labels, import/export |
| **List views** | Table default, card view for specific entities (e.g. assets with photos) |
| **Keyboard** | Full keyboard navigation (like Linear) — Cmd+K, shortcuts for all common actions |
### Dashboard Widgets
| Widget | Description |
| ------------------------------- | ---------------------------------- |
| Upcoming events | Next 7/14/30 days |
| Equipment utilisation overview | Usage rates across categories |
| Open quotes / pending approvals | Awaiting client or internal action |
| Overdue returns / missing items | Equipment past return deadline |
| Revenue summary | Period revenue with trend |
| Low-stock consumable alerts | Below reorder threshold |
| Crew availability overview | Available vs booked crew |
| Recent activity feed | Latest system-wide actions |
---
@@ -357,6 +435,20 @@ erDiagram
| **Webhooks** | ✅ Yes | Outbound webhooks for third-party integration |
| **SMS** | ❌ No | Not planned |
### Webhook Events
All major entity changes trigger outbound webhooks:
| Event Category | Examples |
| -------------- | ------------------------------------------------ |
| **Assets** | Status changed (checked out, returned, damaged) |
| **Events** | Status changed (confirmed, completed, cancelled) |
| **Quotes** | Approved / rejected by client |
| **Invoices** | Paid, overdue |
| **Stock** | Low stock alert |
| **Federation** | Sub-hire request, asset transfer |
| **CRUD** | Create / update / delete on any major entity |
---
## Monitoring & Observability
@@ -371,15 +463,78 @@ erDiagram
---
## Reporting
| Feature | Description |
| ------------------------- | -------------------------------------------------- |
| **Output formats** | In-app, PDF, CSV/Excel, scheduled email delivery |
| **Predefined reports** | Standard reports with filters and grouping |
| **Custom report builder** | Drag-and-drop fields, custom calculations (future) |
| **Roadmap** | Predefined + filters for MVP, full builder later |
---
## Document Generation
| Feature | Description |
| ---------------------- | --------------------------------------------------------- |
| **Branding** | Company logo + name + colours for MVP |
| **Full templates** | Header, footer, fonts, layout customisation (future) |
| **Template engine** | HTML/CSS templates — users can provide their own (future) |
| **Document numbering** | Configurable prefix + sequence per document type |
---
## Data Retention & Files
| Feature | Description |
| -------------------- | ------------------------------------------------------------------- |
| **Retention policy** | Configurable per entity type (e.g. events: 5 years, audit: 7 years) |
| **Legal compliance** | Follow Austrian/EU legal requirements (varies by document type) |
| **File versioning** | Keep version history (v1, v2, v3) when files are updated |
---
## Notifications
| Feature | Description |
| -------------------- | ---------------------------------------------------------------- |
| **User preferences** | Granular per-event-type toggle (future feature) |
| **Email templates** | Tenant-branded for MVP (logo, colours), full customisation later |
---
## API & Extensibility
| Feature | Description |
| --------------------- | ------------------------------------------------------------- |
| **API documentation** | Auto-generated from Protobuf definitions (buf.build registry) |
| **MVP docs** | Minimal — just the `.proto` files |
| **Plugin system** | Design for extensibility now, implement plugin API later |
| **Webhooks** | Primary extensibility mechanism for MVP |
---
## Testing & Environments
| Feature | Description |
| ------------------------ | ----------------------------------------------------------------------- |
| **Testing strategy** | Whatever ships fastest with confidence |
| **Staging environments** | Ephemeral preview environments per PR (Kubernetes-native, not priority) |
| **Local development** | Docker Compose for local dev stack |
---
## 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 |
| Feature | Description |
| ----------------------- | ---------------------------------------------------------------------------- |
| **i18n framework** | Built-in from the start — translations added incrementally |
| **MVP languages** | English + German |
| **Multi-currency** | Configurable from the start — currency, tax rates, tax ID formats per tenant |
| **Timezone support** | Per-user timezone, event times stored in UTC |
| **Date/number formats** | Locale-aware formatting (e.g. `dd.MM.yyyy` for DE, `MM/dd/yyyy` for EN) |
| **Right-to-left** | RTL layout support for applicable languages (future) |
---