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

118
Test/EventKit/00 - System Overview.md Normal file
View File

@@ -0,0 +1,118 @@
---
tags:
- eventkit
---
# EventKit — System Overview
## Vision
EventKit is a **decentralised, [[04 - Federation Architecture|federated]]** [[01 - Inventory Management|inventory management]], [[02 - Planning Module|planning]], and [[03 - CRM Module|CRM]] platform purpose-built for the **event industry**. Each company hosts its own instance with full data sovereignty, while optional federation enables cross-company workflows like sub-hire tracking, equipment sharing, and inter-company asset visibility.
---
## Core Modules
| Module | Purpose | |
| ------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------- |
| 01 - Inventory Management | Inventory Management | Track equipment assets, flight cases, consumables, warehouse locations, maintenance, and availability |
| 02 - Planning Module | Event Planning | Manage events end-to-end — pull lists, crew scheduling, transport/logistics, timelines, and venue specs |
| 03 - CRM Module | CRM | Client relationships, sales pipeline, quoting, invoicing, and communication tracking |
---
## Key Differentiators
### 1. Event-Industry Specialised
Not a generic inventory tool — built around the realities of event production:
- Equipment goes **out and comes back** (rental cycle, not linear supply chain)
- Assets live in **[[01 - Inventory Management#Cases & Packing|flight cases]]** and move between **warehouses and venues**
- Everything is driven by **[[02 - Planning Module|event dates and schedules]]**
- **[[01 - Inventory Management#Sub-hire Management|Sub-hire]]** between companies is a first-class workflow
### 2. Decentralised / Federated
- Every company runs their **own instance** with full control over their data
- Instances can **[[04 - Federation Architecture|federate]]** with trusted partners for cross-company workflows
- No central authority or vendor lock-in
- Equipment can be **[[04 - Federation Architecture#Global Asset Identity|tracked across company boundaries]]** via federation
### 3. Barcode / QR Code Scanning
- Every asset, case, and warehouse location gets a **[[05 - Barcode and QR Scanning#QR Code Design|scannable QR code]]**
- QR codes encode a **URL** — works with any phone camera or dedicated scanner
- Scanning powers [[05 - Barcode and QR Scanning#Scanning Workflows|workflows]]: check-out, check-in, stocktake, case packing, sub-hire receive/return
---
## System Architecture
```mermaid
graph TB
subgraph "Single Instance"
UI["Web UI / PWA"]
Scanner["Scanner Module"]
API["API Server"]
Fed["Federation Service"]
Worker["Background Workers"]
DB[(Database)]
Files[(File Storage)]
UI --> API
Scanner --> API
API --> DB
API --> Files
API --> Fed
API --> Worker
Worker --> DB
end
Fed <-->|"Federation Protocol\n(mTLS + signed requests)"| ExtFed["Other Instances"]
```
---
## Module Interaction
```mermaid
graph LR
CRM["CRM"] -->|"Client enquiry\n→ create event"| Planning["Planning"]
Planning -->|"Reserve equipment\nfrom pull list"| Inventory["Inventory"]
Planning -->|"Book crew &\narrange transport"| Resources["Crew & Transport"]
Inventory -->|"Availability data &\npricing"| Planning
Inventory -->|"Equipment costs"| CRM
CRM -->|"Client & pricing"| Planning
Planning -->|"Final costs & usage"| CRM
```
---
## Terminology
| Term | Definition |
| ---------------------- | ----------------------------------------------------------------------- |
| **Instance** | A single company's deployment of EventKit |
| Federation | The protocol enabling inter-instance communication |
| Asset | An individual, trackable piece of equipment (with serial number / UUID) |
| **Product / Model** | A type of equipment — assets are instances of a product |
| **Case / Flight Case** | A container holding multiple assets, tracked as its own entity |
| **Kit / Set** | A logical grouping of equipment that typically deploys together |
| Event | A job/gig — the core planning entity |
| Pull List | The equipment list required for a specific event |
| Sub-hire | Borrowing or lending equipment between companies |
| Consumable | Items that don't return (tape, batteries, haze fluid) |
---
## Related Documentation
- [[01 - Inventory Management]] — Equipment, cases, locations, maintenance
- [[02 - Planning Module]] — Events, crew, transport, scheduling
- [[03 - CRM Module]] — Clients, pipeline, quotes
- [[04 - Federation Architecture]] — Decentralised design & protocol
- [[05 - Barcode and QR Scanning]] — Scanning workflows & label design
- [[06 - Module Integration]] — Cross-module flows
- [[07 - Technical Requirements]] — Non-functional requirements
- [[08 - Open Questions]] — Remaining decisions

186
Test/EventKit/01 - Inventory Management.md Normal file
View File

@@ -0,0 +1,186 @@
---
tags:
- eventkit
---
# Inventory Management Module
## Purpose
Track and manage all physical equipment assets throughout their lifecycle — from procurement through daily rental operations to maintenance and retirement. Specialised for the event industry's unique needs: equipment goes out to [[02 - Planning Module|events]], gets used, and comes back.
---
## Core Concepts
### Entity Hierarchy
```mermaid
graph TD
Product["Product / Model\n(e.g. Shure SM58)"]
Asset["Asset\n(Serial: SM58-00142)"]
Case["Flight Case\n(Case #FC-210)"]
Kit["Kit / Set\n(DJ Booth Kit)"]
Location["Location\n(Warehouse A, Shelf B3)"]
Consumable["Consumable\n(Gaffer Tape, Batteries)"]
Product -->|"has many"| Asset
Case -->|"contains"| Asset
Kit -->|"groups"| Product
Location -->|"stores"| Asset
Location -->|"stores"| Case
Location -->|"stores"| Consumable
```
### Entity Definitions
| Entity | Description | Tracking |
| ---------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **Product / Model** | A type of equipment (e.g. "Shure SM58 Microphone") | Category, specs, weight, dimensions, photos, manuals |
| **Asset** | A single physical item with a unique identity | Serial number, UUID, QR code, purchase date, cost, condition |
| **Case / Flight Case** | A container holding multiple assets | Case UUID, contents (packing list), weight, dimensions, label |
| **Kit / Set** | A logical grouping of products/assets that typically deploy together | Component list, auto-expansion on pull lists |
| **Location** | Where assets live — warehouse, shelf, venue, truck, repair shop, sub-hire partner | Address, type, capacity, contact |
| **Consumable** | Non-returnable stock items | Product ID, stock level, reorder point, par level |
---
## Asset Lifecycle & Statuses
```mermaid
stateDiagram-v2
[*] --> Available : Purchased / registered
Available --> Reserved : Allocated to event
Reserved --> CheckedOut : Dispatched
CheckedOut --> OnSite : Arrived at venue
OnSite --> CheckedOut : Strike / departed venue
CheckedOut --> CheckedIn : Returned to warehouse
CheckedIn --> Available : Passed inspection
CheckedIn --> Damaged : Failed inspection
Damaged --> InRepair : Sent for repair
InRepair --> Available : Repair complete
Damaged --> WrittenOff : Beyond repair
Available --> SubHiredOut : Lent to partner
SubHiredOut --> CheckedIn : Returned from sub-hire
Available --> Retired : End of life
```
### Status Definitions
| Status | Description |
| ----------------- | ----------------------------------------------- |
| **Available** | In warehouse, ready for use |
| **Reserved** | Allocated to a future event, not yet dispatched |
| **Checked Out** | Left the warehouse — in transit or en route |
| **On-Site** | Confirmed at event venue |
| **Checked In** | Returned to warehouse, awaiting inspection |
| **In Repair** | At repair shop or undergoing maintenance |
| **Damaged** | Flagged during return inspection |
| **Lost** | Missing — cannot be located |
| **Written Off** | Beyond economic repair or permanently lost |
| **Sub-hired Out** | Lent to another company (federated tracking) |
| **Sub-hired In** | Borrowed from another company via federation |
| **Retired** | End of life, no longer in active inventory |
---
## Feature Breakdown
### Asset Register
| Feature | Description |
| --------------------------- | --------------------------------------------------------------------------------------------------- |
| Individual asset tracking | Each asset has a UUID, serial number, and QR code |
| Purchase & financial data | Purchase date, supplier, cost, insurance value, depreciation |
| Documentation | Photos, manuals, spec sheets, certificates attached per asset |
| Firmware / version tracking | Track software/firmware versions on digital equipment |
| Custom attributes | User-defined fields per product category (e.g. "wattage" for amps, "throw distance" for projectors) |
| Condition notes | Free-text notes updated at each check-in inspection |
| Full audit trail | Every status change, location change, and edit is logged with timestamp and user |
### Cases & Packing
| Feature | Description |
| ------------------------- | ---------------------------------------------------------------------------- |
| Case as entity | Each case has its own UUID, QR code, weight, and dimensions |
| Contents management | Define what assets are packed in each case |
| Packing list generation | Printable packing list per case |
| Case label printing | Print QR-coded labels for case lids |
| Smart packing suggestions | System suggests optimal case allocation based on pull list and case capacity |
| Nested cases | Support for cases within cases (e.g. small pelican cases inside a trunk) |
| Weight calculation | Auto-calculate total case weight from contents |
### Warehouse & Locations
| Feature | Description |
| ------------------------------ | ------------------------------------------------------ |
| Multiple warehouses | Support any number of storage locations |
| Bin/shelf/bay/rack locations | Granular location tracking within a warehouse |
| Visual warehouse map | Optional visual layout showing where items are stored |
| Check-in / check-out workflows | Scanning-based workflows for dispatching and receiving |
| Stock transfers | Move assets between warehouses with full tracking |
| Location-based stocktake | Scan everything at a location, flag discrepancies |
### Availability Engine
| Feature | Description |
| ---------------------- | ---------------------------------------------------------------- |
| Real-time availability | See what's available for any date range, per product or category |
| Conflict detection | Alert when the same asset is double-booked across events |
| Availability search | "Show me 10× available SM58s for March 15-18" |
| Calendar view | Heatmap-style availability calendar showing utilisation density |
| Shortage alerts | Warn planners when demand exceeds available stock |
### Sub-hire Management
| Feature | Description |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| Outbound sub-hire | Track equipment lent to other companies |
| Inbound sub-hire | Track equipment borrowed from others |
| Federated sub-hire | When both companies use EventKit, track the asset across instances (see [[04 - Federation Architecture]]) |
| Sub-hire rates & costs | Track day rates, insurance charges, cross-charges |
| Return deadline tracking | Alerts for overdue sub-hire returns |
| Condition tracking | Record condition at dispatch and return for dispute resolution |
### Consumables
| Feature | Description |
| -------------------------- | ------------------------------------------------------- |
| Stock level tracking | Current quantity per consumable product |
| Reorder thresholds | Automated alerts when stock falls below a defined level |
| Par levels | Target stock levels to maintain |
| Consumption per event | Track how much of each consumable was used per event |
| Purchase order integration | Generate POs to restock consumables |
### Maintenance & Testing
| Feature | Description |
| -------------------------- | ------------------------------------------------------------------------ |
| PAT testing records | Track Portable Appliance Testing dates and results per asset |
| Service schedules | Define recurring maintenance intervals (e.g. every 12 months) |
| Next-service-due reminders | Automated alerts for upcoming maintenance |
| Repair history | Full repair log per asset — what was done, cost, duration |
| Maintenance cost tracking | Aggregate repair costs per asset for ROI analysis |
| Certification tracking | Track certifications with expiry dates (rigging gear, fire safety, etc.) |
### Reporting & Analytics
| Report | Description |
| ------------------------- | ------------------------------------------------------------------------------ |
| Utilisation rate | % of time each asset/category is in use vs. available |
| Revenue per asset | Income generated per individual asset or category (linked to CRM revenue data) |
| Maintenance cost analysis | Total maintenance spend per asset, category, or period |
| Loss & damage rate | Frequency and cost of losses and damages |
| ABC analysis | Categorise inventory by value/usage (A = high, C = low) |
| Stock aging | How long items have been sitting unused |
| Insurance valuation | Current value of all assets for insurance purposes |
| Depreciation report | Book value vs. purchase price over time |
---
## Related Documentation
- [[00 - System Overview]] — High-level system overview
- [[02 - Planning Module]] — Event planning and pull lists consume inventory data
- [[05 - Barcode and QR Scanning]] — Scanning workflows for check-in/out
- [[04 - Federation Architecture]] — Cross-company asset tracking

188
Test/EventKit/02 - Planning Module.md Normal file
View File

@@ -0,0 +1,188 @@
---
tags:
- eventkit
---
# Planning Module
## Purpose
Manage the full lifecycle of events — from initial [[03 - CRM Module|enquiry]] through on-site execution to post-event close-out. Co-ordinates [[01 - Inventory Management|equipment]], crew, transport, and venue logistics into a single operational view.
---
## Core Concepts
### Entity Hierarchy
```mermaid
graph TD
Project["Project\n(e.g. Summer Tour 2026)"]
Event["Event\n(e.g. London O2 - June 14)"]
PullList["Pull List\n(Equipment needed)"]
CrewAssignment["Crew Assignments"]
Load["Load / Truck Pack"]
Venue["Venue\n(O2 Arena)"]
Project -->|"contains"| Event
Event -->|"has"| PullList
Event -->|"has"| CrewAssignment
Event -->|"has"| Load
Event -->|"at"| Venue
```
### Entity Definitions
| Entity | Description |
| --------------------- | ------------------------------------------------------------------------------------------------- |
| **Project** | A group of related events (a tour, a festival with multiple stages, a recurring corporate series) |
| **Event / Job** | The core planning unit — a single gig, show, or production with defined dates and a venue |
| **Pull List** | The specific equipment list needed for an event, built from the product catalogue |
| **Load / Truck Pack** | The physical shipment — what goes on which truck, weights, volumes |
| **Crew Assignment** | Who is working the event, in what role, for what hours |
| **Venue** | The location where the event takes place, with its own technical specifications |
---
## Event Lifecycle
```mermaid
stateDiagram-v2
[*] --> Enquiry
Enquiry --> Quoted : Quote sent
Quoted --> Confirmed : Client confirms
Quoted --> Cancelled : Client declines
Confirmed --> Prep : Prep begins
Prep --> LoadOut : Equipment dispatched
LoadOut --> OnSite : Arrived at venue
OnSite --> LoadIn : Strike complete
LoadIn --> DePrep : Equipment returned
DePrep --> Closed : Inspected & invoiced
```
### Phase Definitions
| Phase | Key Activities |
| -------------------- | --------------------------------------------------------------------------- |
| **Enquiry** | Initial client request received, feasibility & availability check |
| **Quoted** | Equipment list + pricing + crew costs + transport costs sent to client |
| **Confirmed** | Client accepted — stock reserved, crew booked, transport arranged |
| **Prep** | Equipment pulled from warehouse, tested, cases packed, prep notes generated |
| **Load-Out** | Equipment dispatched — truck pack list signed off, driver assigned |
| **On-Site** | Setup → show → strike. On-site issue tracking, additional requests |
| **Load-In (Return)** | Equipment returns to warehouse |
| **De-Prep** | Return inspection, damage reporting, cleaning, re-shelving |
| **Closed** | Final invoicing, profit/loss analysis, post-event review notes |
| **Cancelled** | Event cancelled — reserved stock released, cancellation fees applied |
---
## Feature Breakdown
### Event / Job Management
| Feature | Description |
| --------------------- | --------------------------------------------------------------- |
| Event creation | Dates (setup, show, strike), venue link, client link (→ CRM) |
| Multi-day events | Events spanning multiple days with per-day schedules |
| Multi-venue events | Festivals or events with multiple stages/spaces |
| Project grouping | Group related events under a project (tours, recurring shows) |
| Event status workflow | Progress through lifecycle phases with validation rules |
| Event templates | Save and reuse event configurations for recurring job types |
| Event duplication | Clone an event as a starting point for a similar job |
| Internal notes | Free-text notes, checklists, and file attachments per event |
| Event tags | Categorise events (corporate, festival, wedding, concert, etc.) |
### Pull Lists / Equipment Planning
| Feature | Description |
| ---------------------- | ------------------------------------------------------------------- |
| Build from catalogue | Add products/kits from the inventory catalogue to the pull list |
| Kit/set expansion | Adding a kit auto-adds all component products |
| Availability check | Real-time check against inventory — green/amber/red indicators |
| Conflict detection | Alert if requested equipment is already booked elsewhere |
| Shortage handling | When stock is short, suggest sub-hire or alternative products |
| Quantity management | Request quantities by product, system allocates specific assets |
| Weight & volume totals | Auto-calculate total weight and volume for transport planning |
| Pull list printing | Printable pull list for warehouse prep team |
| Pull list versioning | Track changes to the pull list over time |
| Category grouping | Group pull list items by category (audio, lighting, video, staging) |
### Crew Planning
| Feature | Description |
| ----------------------- | ------------------------------------------------------------------------ |
| Crew database | Profiles with skills, certifications, contact details, rates |
| Availability calendar | Per-crew-member availability with blocked/booked dates |
| Role-based assignment | Assign crew by role: sound engineer, lighting tech, rigger, driver, etc. |
| Skill matching | Filter available crew by required skills/certifications |
| Crew costs per event | Track day rates, overtime, expenses per crew member per event |
| Shift scheduling | Define shift start/end times per crew member per event day |
| Crew notifications | Notify assigned crew via email/SMS with event details |
| Freelancer vs. in-house | Distinguish between employed staff and freelance contractors |
| Timesheet capture | Record actual hours worked for payroll/invoicing |
### Transport & Logistics
| Feature | Description |
| ----------------- | ------------------------------------------------------------------ |
| Vehicle fleet | Manage owned/hired vans and trucks with capacities |
| Truck pack lists | Define what goes on which vehicle, with weight/volume calculations |
| Weight limits | Warn when truck pack exceeds vehicle capacity |
| Driver assignment | Assign drivers with licence validation |
| Route planning | Basic route info or integration with mapping services |
| Dispatch tracking | Track when vehicles leave warehouse and arrive at venue |
| Return tracking | Track when vehicles return from venue |
### Venue Management
| Feature | Description |
| ---------------- | ---------------------------------------------------------------- |
| Venue database | Venues with addresses, contacts, and technical specifications |
| Technical specs | Power supply details, rigging points, dimensions, load-in access |
| Site plans | Attach CAD files, PDFs, or images of venue layouts |
| Technical riders | Store standard technical requirements per venue |
| Venue contacts | Key contacts: production manager, venue technician, security |
| Blackout dates | Track dates when a venue is unavailable |
| Venue history | See all past events at a venue with notes |
### Timeline & Scheduling
| Feature | Description |
| --------------------- | -------------------------------------------------------------------------------- |
| Gantt-style timeline | Visual timeline of events with setup/show/strike phases |
| Per-event schedule | Detailed schedule: load-in time, setup, rehearsal, doors, show, strike, load-out |
| Milestone tracking | Key milestones with due dates and notification |
| Dependency management | Task B can't start until Task A completes |
| Recurring schedules | For events with repeating structures |
### Calendar Views
| View | Description |
| ---------------------- | ----------------------------------------------------------------- |
| Company event calendar | All events across the company, filterable by type/client/crew |
| Equipment availability | Heatmap calendar showing utilisation density per product/category |
| Crew availability | Who is available on which dates |
| Warehouse calendar | Scheduled load-outs and load-ins per day |
| Vehicle calendar | Vehicle booking and availability |
### Reporting
| Report | Description |
| ----------------------- | ------------------------------------------------------------ |
| Events per period | Count and breakdown of events by week/month/quarter |
| Revenue per event | Total revenue and margin per event |
| Revenue per client | Client ranking by revenue |
| Crew utilisation | Percentage of available days booked per crew member |
| Vehicle utilisation | Percentage of available days booked per vehicle |
| Profitability per event | Revenue minus equipment, crew, transport, and sub-hire costs |
| On-time performance | Load-out and load-in schedule adherence |
---
## Related Documentation
- [[00 - System Overview]] — High-level system overview
- [[01 - Inventory Management]] — Equipment data consumed by pull lists
- [[03 - CRM Module]] — Client data and pipeline feed into event creation
- [[06 - Module Integration]] — How planning connects to inventory and CRM

155
Test/EventKit/03 - CRM Module.md Normal file
View File

@@ -0,0 +1,155 @@
---
tags:
- eventkit
---
# CRM Module
## Purpose
Manage client relationships, sales pipeline, quoting, and communication for event companies. Tightly integrated with the [[02 - Planning Module]] (won deals become events) and [[01 - Inventory Management]] (quotes reference real equipment and pricing).
---
## Core Concepts
```mermaid
graph TD
Company["Company / Organisation"]
Contact["Contact / Person"]
Lead["Lead"]
Deal["Deal / Opportunity"]
Quote["Quote"]
Invoice["Invoice"]
Activity["Activity\n(call, email, meeting)"]
Company -->|"has many"| Contact
Lead -->|"converts to"| Deal
Deal -->|"belongs to"| Company
Deal -->|"has"| Quote
Deal -->|"generates"| Invoice
Contact -->|"has many"| Activity
Deal -->|"has many"| Activity
```
---
## Sales Pipeline
### Default Stages
```mermaid
graph LR
Lead["Lead"] --> Qualified["Qualified"]
Qualified --> Proposal["Proposal Sent"]
Proposal --> Negotiation["Negotiation"]
Negotiation --> Won["Won ✅"]
Negotiation --> Lost["Lost ❌"]
```
Stages are **fully customisable** per instance. Multiple pipelines can exist (e.g. one for equipment hire, another for production services).
---
## Feature Breakdown
### Contact Management
| Feature | Description |
| -------------------- | --------------------------------------------------------------- |
| Companies & contacts | Separate entities linked together — one company, many contacts |
| Contact segmentation | Tags, categories, and custom fields for filtering |
| Interaction history | Full timeline of calls, emails, meetings, and notes per contact |
| Duplicate detection | Warn when creating contacts with similar names/emails |
| Import / export | CSV import for initial migration, bulk export |
| Custom fields | User-defined fields per company and contact |
### Sales Pipeline
| Feature | Description |
| ------------------------ | --------------------------------------------------------- |
| Visual pipeline | Drag-and-drop deal cards across stages |
| Deal value & probability | Expected revenue with weighted probability |
| Weighted forecast | Pipeline value weighted by probability per stage |
| Multiple pipelines | Separate pipelines for different service lines |
| Win/loss analysis | Track reasons for winning or losing deals |
| Pipeline reporting | Conversion rates, average deal size, sales cycle duration |
### Lead Management
| Feature | Description |
| ---------------------- | -------------------------------------------------------------- |
| Lead capture | Web forms, API, manual entry |
| Lead source tracking | Where the lead came from (website, referral, trade show, etc.) |
| Lead scoring | Automatic or manual scoring to prioritise follow-up |
| Lead assignment | Rules-based or manual assignment to sales reps |
| Lead → Deal conversion | Convert a qualified lead into a deal with one click |
### Quoting
| Feature | Description |
| ------------------- | ---------------------------------------------------------------- |
| Quote builder | Build quotes from the equipment catalogue with real-time pricing |
| Line items | Equipment hire, crew costs, transport, consumables, sub-hire |
| Discount management | Per-line or overall discounts with approval workflows |
| Quote versioning | Track revisions sent to the client |
| Quote templates | Reusable templates for common job types |
| PDF generation | Professional, branded quote PDFs |
| Quote → Event | Accepted quote auto-creates an event in the Planning module |
| Availability check | Verify equipment availability while building the quote |
### Communication
| Feature | Description |
| ------------------ | ---------------------------------------------------------- |
| Email integration | Send/receive emails from within the CRM (IMAP/SMTP or API) |
| Email templates | Reusable templates for common communications |
| Call logging | Log phone calls with notes and outcomes |
| Meeting scheduling | Schedule and track meetings |
| Activity timeline | Unified feed of all interactions per contact/company/deal |
### Invoicing (Basic)
| Feature | Description |
| ----------------------- | ------------------------------------------------------- |
| Invoice generation | Generate invoices from confirmed quotes or events |
| Line item detail | Equipment, crew, transport, consumables, sub-hire costs |
| Invoice status tracking | Draft → Sent → Paid → Overdue |
| Payment tracking | Record payments received |
| Accounting integration | Export to or sync with Xero, QuickBooks, etc. |
| Credit notes | Issue credit for cancellations or adjustments |
### Reporting
| Report | Description |
| --------------------- | ------------------------------------------------------- |
| Sales dashboard | Pipeline value, deals won/lost, revenue by period |
| Rep performance | Deals per rep, conversion rate, average deal value |
| Client ranking | Top clients by revenue, frequency, or lifetime value |
| Revenue forecast | Projected revenue from pipeline weighted by probability |
| Lead source ROI | Which lead sources generate the most revenue |
| Quote conversion rate | What percentage of quotes become confirmed events |
---
## Event Industry CRM Specifics
Unlike generic CRMs, the EventKit CRM understands:
| Concept | How It Applies |
| ------------------------- | ---------------------------------------------------------------------- |
| **Seasonal demand** | Dashboard shows booking density, warns about capacity in peak season |
| **Repeat clients** | Track client event history, preferences, and standard setups |
| **Technical riders** | Store client technical requirements for quick quoting |
| **Venue preferences** | Link clients to preferred venues |
| **Equipment preferences** | Record client brand/model preferences for future quotes |
| **Event types** | Categorise deals by event type (corporate, concert, wedding, festival) |
---
## Related Documentation
- [[00 - System Overview]] — High-level system overview
- [[02 - Planning Module]] — Won deals become events
- [[01 - Inventory Management]] — Quotes reference equipment catalogue
- [[06 - Module Integration]] — CRM ↔ Planning ↔ Inventory flows

393
Test/EventKit/04 - Federation Architecture.md Normal file
View File

@@ -0,0 +1,393 @@
---
tags:
- eventkit
---
# Federation Architecture
## Purpose
Enable multiple EventKit instances to communicate securely, allowing cross-company workflows like [[01 - Inventory Management#Sub-hire Management|sub-hire tracking]], equipment availability queries, and cross-boundary [[05 - Barcode and QR Scanning|asset tracking]] — while each company retains full sovereignty over their own data.
---
## Design Principles
| Principle | Description |
| -------------------------- | ------------------------------------------------------------------------------------- |
| **Data sovereignty** | Each instance owns its data. Nothing is shared without explicit configuration |
| **Opt-in federation** | Federation is optional. An instance works fully standalone |
| **Mutual trust** | Both parties must agree to federate. Either can revoke at any time |
| **Minimal exposure** | Only share what's needed. Internal events, clients, crew, and costs are never exposed |
| **Cryptographic identity** | Instances authenticate via key pairs and mutual TLS |
| **Eventual consistency** | Federation is async — network outages don't break local operations |
| **Hosting agnostic** | Federation works identically regardless of where or how an instance is hosted |
---
## Deployment & Hosting Models
Federation operates at the **application protocol level**, not the infrastructure level. This means instances federate identically whether they are self-hosted, on dedicated servers, or sharing infrastructure via a managed hosting provider.
### Three Hosting Tiers
```mermaid
graph TB
subgraph "Managed SaaS Provider"
subgraph "Company A (Tenant)"
A_App["App A"]
A_DB[(DB A)]
end
subgraph "Company B (Tenant)"
B_App["App B"]
B_DB[(DB B)]
end
end
subgraph "Dedicated Hosting Provider"
subgraph "Company C (Isolated VM)"
C_App["App C"]
C_DB[(DB C)]
end
end
subgraph "Company D (Self-Hosted)"
D_App["App D"]
D_DB[(DB D)]
end
A_App <-->|"Federation"| B_App
A_App <-->|"Federation"| C_App
B_App <-->|"Federation"| D_App
C_App <-->|"Federation"| D_App
```
| Tier | Model | Data Isolation | Best For |
| -------------------- | --------------------------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------- |
| **Managed SaaS** | Multiple companies on shared infrastructure, each with their own database and subdomain | Logical (separate DBs, same server) | Small companies wanting zero ops overhead |
| **Dedicated Hosted** | Isolated instance on a hosting provider's infrastructure (own VM/container) | Physical (separate VMs) | Mid-size companies wanting isolation without self-hosting |
| **Self-Hosted** | Company runs their own server on their own infrastructure | Full physical | Large companies or those with strict data sovereignty needs |
### How It Works Per Tier
#### Managed SaaS
- A hosting provider runs many EventKit instances on shared infrastructure
- Each company gets their own **subdomain** (e.g. `companya.eventkit.io`, `companyb.eventkit.io`)
- Each company has a **separate database** — data is never mixed
- Companies on the **same provider** federate through the same protocol as external instances
- The provider can optionally optimise same-host federation (internal routing instead of public internet), but the protocol remains identical
- Think of it like **email hosting** — Gmail hosts millions of accounts, but they all speak SMTP to each other and to self-hosted mail servers
#### Dedicated Hosted
- A hosting provider runs a **dedicated VM or container** per company
- Full resource isolation — own CPU, memory, storage
- Company gets a **custom domain** or provider subdomain
- Provider handles updates, backups, and monitoring
- Federates identically to self-hosted instances
#### Self-Hosted
- Company downloads EventKit and runs it on their own infrastructure
- Full control over data, updates, and configuration
- Requires technical staff to manage
- Federates with any other instance regardless of how it's hosted
### Federation Transparency
A critical design property: **no instance can tell how another instance is hosted**. The federation protocol is the same regardless:
| Scenario | Federation Behaviour |
| ----------------------------------------- | ----------------------------------------------------------------------- |
| SaaS tenant ↔ SaaS tenant (same provider) | Standard federation protocol (provider may optimise routing internally) |
| SaaS tenant ↔ Self-hosted | Standard federation protocol over the internet |
| Self-hosted ↔ Self-hosted | Standard federation protocol over the internet |
| Dedicated hosted ↔ SaaS tenant | Standard federation protocol |
### Hosting Provider Responsibilities
If a hosting provider offers managed EventKit instances, their responsibilities include:
| Responsibility | Description |
| -------------------- | ------------------------------------------------------------------ |
| **Provisioning** | Spin up new instances with a domain, database, and TLS certificate |
| **Isolation** | Ensure tenant data is never accessible to other tenants |
| **Updates** | Roll out EventKit updates across managed instances |
| **Backups** | Automated backups per tenant with restore capability |
| **Monitoring** | Health checks, uptime monitoring, alerting |
| **TLS certificates** | Manage certificates for federation (mTLS) and web access |
| **DNS** | Manage subdomains or custom domain mapping |
### Multi-Tenant vs. Multi-Instance (Provider Implementation)
Hosting providers can choose their internal architecture:
| Approach | Description | Pros | Cons |
| ---------------------------- | ----------------------------------------------- | ----------------------------------- | ----------------------------------------- |
| **Multi-instance** | One container/VM + database per tenant | Strongest isolation, simple ops | Higher resource cost per tenant |
| **Shared app, separate DBs** | One application pool, one database per tenant | Lower resource cost, easier updates | Moderate isolation |
| **True multi-tenant** | One application, one database, tenant ID column | Lowest cost | Weakest isolation, complex access control |
**Recommended for providers**: Multi-instance (containerised) for the best balance of isolation and operability. Each tenant gets a Docker container + PostgreSQL database, managed via orchestration (e.g. Kubernetes).
---
## Instance Architecture
```mermaid
graph TB
subgraph "Single Instance (any hosting tier)"
A_Core["Core Application"]
A_Fed["Federation Service"]
A_DB[(Database)]
A_Core --> A_Fed
A_Core --> A_DB
end
subgraph "Partner Instance (any hosting tier)"
B_Core["Core Application"]
B_Fed["Federation Service"]
B_DB[(Database)]
B_Core --> B_Fed
B_Core --> B_DB
end
A_Fed <-->|"mTLS + Signed Requests"| B_Fed
```
### Components
| Component | Role |
| ---------------------- | ------------------------------------------------------------------------------------------ |
| **Core Application** | The main EventKit instance — handles all local operations |
| **Federation Service** | A dedicated service/module that handles all inter-instance communication |
| **Trust Store** | Stores public keys and connection details for all trusted partner instances |
| **Outbox / Inbox** | Queue for outbound and inbound federation messages (ensures delivery even during downtime) |
---
## Trust Establishment
### Handshake Flow
```mermaid
sequenceDiagram
participant A as Instance A
participant B as Instance B
Note over A: Admin initiates federation request
A->>B: POST /federation/request
Note right of A: {instance_url, public_key, company_name, contact_email}
B-->>A: 202 Accepted (pending review)
Note over B: Admin reviews request
Note over B: Admin approves
B->>A: POST /federation/confirm
Note right of B: {signed_challenge, public_key, permissions_granted}
A-->>B: 200 OK
Note over A,B: ✅ Federation established
```
### Trust Levels
Companies can grant different permission levels to each partner:
| Level | Permissions |
| ---------------- | ------------------------------------------------------------- |
| **Basic** | View company profile only |
| **Availability** | Query equipment availability for date ranges |
| **Sub-hire** | Request and track sub-hire transactions |
| **Full** | All above + cross-instance asset scanning + condition history |
Trust levels can be **changed or revoked** at any time by either party.
---
## Global Asset Identity
Every asset needs a globally unique identifier that works across instances.
### ID Format
```
UUID: 550e8400-e29b-41d4-a716-446655440000
URN: urn:eventkit:{instance-id}:asset:{uuid}
QR URL: https://inventory.company-a.com/asset/550e8400-e29b-41d4-a716-446655440000
```
| Component | Purpose |
| --------------- | --------------------------------------------------------------------------------- |
| **UUID** | Canonical, globally unique identifier — generated locally, no coordination needed |
| **Instance ID** | Identifies the owning instance — part of the URN for federated lookups |
| **QR URL** | Points to the asset's page on the owning instance — works with any phone camera |
### Asset Resolution
When scanning an asset that belongs to another instance:
```mermaid
sequenceDiagram
participant Scanner as Company B (Scanner)
participant B_API as Company B Instance
participant A_API as Company A Instance
Scanner->>B_API: Scan QR → URL: company-a.com/asset/{uuid}
B_API->>B_API: URL domain ≠ local → federated asset
B_API->>A_API: GET /federation/asset/{uuid}
A_API->>A_API: Check: Is Company B a trusted partner?
A_API-->>B_API: 200 OK {asset_details, status, condition}
B_API-->>Scanner: Display asset info + "Owned by Company A"
```
---
## Federation API (gRPC via ConnectRPC)
Federation between instances uses **gRPC over HTTP/2** with mTLS. The API is defined in Protocol Buffers and served via ConnectRPC, meaning it also supports the Connect protocol (HTTP/1.1 + JSON) for debugging and testing.
### Protobuf Service Definition
```protobuf
// proto/eventkit/v1/federation.proto
syntax = "proto3";
package eventkit.v1;
service FederationService {
// Trust management
rpc RequestFederation(FederationRequest) returns (FederationRequestResponse);
rpc ConfirmFederation(FederationConfirm) returns (FederationConfirmResponse);
rpc RevokeFederation(RevokeFederationRequest) returns (RevokeFederationResponse);
rpc ListPartners(ListPartnersRequest) returns (ListPartnersResponse);
// Availability
rpc QueryAvailability(AvailabilityQuery) returns (AvailabilityResponse);
rpc QueryProductAvailability(ProductAvailabilityQuery) returns (ProductAvailabilityResponse);
// Sub-hire
rpc RequestSubhire(SubhireRequest) returns (SubhireResponse);
rpc AcceptSubhire(SubhireActionRequest) returns (SubhireActionResponse);
rpc RejectSubhire(SubhireActionRequest) returns (SubhireActionResponse);
rpc DispatchSubhire(SubhireActionRequest) returns (SubhireActionResponse);
rpc ReceiveSubhire(SubhireActionRequest) returns (SubhireActionResponse);
rpc ReturnSubhire(SubhireActionRequest) returns (SubhireActionResponse);
rpc ListSubhires(ListSubhiresRequest) returns (ListSubhiresResponse);
// Asset resolution
rpc GetAsset(GetFederatedAssetRequest) returns (FederatedAsset);
rpc ReportAssetCheckin(AssetCheckinReport) returns (AssetReportResponse);
rpc ReportAssetCheckout(AssetCheckoutReport) returns (AssetReportResponse);
rpc ReportAssetDamage(AssetDamageReport) returns (AssetReportResponse);
// Real-time event stream (server-streaming)
rpc SubscribeEvents(SubscribeEventsRequest) returns (stream FederationEvent);
}
```
### RPC Reference
| Category | RPC Method | Purpose |
| ---------------- | -------------------------- | ----------------------------------------------------- |
| **Trust** | `RequestFederation` | Initiate federation handshake with a partner instance |
| **Trust** | `ConfirmFederation` | Accept a incoming federation request |
| **Trust** | `RevokeFederation` | Revoke trust — cancels all pending operations |
| **Trust** | `ListPartners` | List current federation partners (local) |
| **Availability** | `QueryAvailability` | Query available equipment for a date range |
| **Availability** | `QueryProductAvailability` | Check specific product availability |
| **Sub-hire** | `RequestSubhire` | Request equipment from a partner |
| **Sub-hire** | `AcceptSubhire` | Accept a sub-hire request |
| **Sub-hire** | `RejectSubhire` | Reject a sub-hire request |
| **Sub-hire** | `DispatchSubhire` | Notify partner that equipment has been dispatched |
| **Sub-hire** | `ReceiveSubhire` | Confirm receipt of sub-hired equipment |
| **Sub-hire** | `ReturnSubhire` | Notify partner that equipment is being returned |
| **Sub-hire** | `ListSubhires` | List all active sub-hire transactions |
| **Asset** | `GetAsset` | Get asset details (respects trust level) |
| **Asset** | `ReportAssetCheckin` | Notify owner: "We received your asset" |
| **Asset** | `ReportAssetCheckout` | Notify owner: "We're returning your asset" |
| **Asset** | `ReportAssetDamage` | Report damage on a partner's asset |
| **Events** | `SubscribeEvents` | Server-streaming RPC for real-time federation events |
### Federation Event Stream
Instead of webhooks, federation uses a **gRPC server-streaming RPC** for real-time notifications. This is more reliable than webhooks (built-in reconnection, backpressure) and works naturally with gRPC:
```protobuf
message FederationEvent {
string event_id = 1;
google.protobuf.Timestamp timestamp = 2;
oneof event {
SubhireRequestedEvent subhire_requested = 10;
SubhireAcceptedEvent subhire_accepted = 11;
SubhireDispatchedEvent subhire_dispatched = 12;
SubhireReceivedEvent subhire_received = 13;
SubhireReturnedEvent subhire_returned = 14;
AssetDamagedEvent asset_damaged = 15;
}
}
```
| Event | Trigger |
| -------------------- | -------------------------------- |
| `subhire_requested` | New sub-hire request received |
| `subhire_accepted` | Sub-hire request accepted |
| `subhire_dispatched` | Equipment dispatched to partner |
| `subhire_received` | Equipment received by partner |
| `subhire_returned` | Equipment returned to owner |
| `asset_damaged` | Asset damage reported by partner |
> [!NOTE]
> The event stream automatically reconnects on disconnection. Events are persisted in the outbox and replayed from the last acknowledged sequence number, so no events are lost during downtime.
---
## Security
| Measure | Description |
| ---------------------- | -------------------------------------------------------------------------------- |
| **mTLS** | Mutual TLS — both instances verify each other's certificate |
| **Request signing** | Each request includes a cryptographic signature using the instance's private key |
| **Scoped permissions** | Tokens carry specific scopes (e.g. `availability:read` ≠ `subhire:write`) |
| **Rate limiting** | Per-partner rate limits to prevent abuse |
| **IP allowlisting** | Optional — restrict federation to known IP ranges |
| **Audit logging** | Every federation interaction is logged on both sides |
| **Data minimisation** | Only share the minimum data needed for the requested operation |
| **Revocation** | Either party can instantly revoke trust — all pending requests are cancelled |
---
## Offline & Resilience
| Scenario | Behaviour |
| --------------------- | -------------------------------------------------------------------------------- |
| **Partner offline** | Outbound messages queue in the outbox; delivered when partner comes back |
| **Network partition** | Local operations continue unaffected; federation syncs when connectivity returns |
| **Conflicting edits** | Owner instance is always the source of truth for asset data |
| **Message ordering** | Messages include timestamps and sequence numbers for correct ordering |
---
## Data Sharing Summary
| Data | Shared with Partners? | Notes |
| ------------------------ | ------------------------ | ---------------------------------------------------------- |
| Company name & contact | ✅ Always | Part of federation profile |
| Equipment catalogue | ✅ If availability trust | Product names, categories, quantities available |
| Individual asset details | ✅ If full trust | UUID, model, condition (owner controls detail level) |
| Equipment pricing | ⚠️ Optional | Owner chooses to share rate cards or negotiate per-request |
| Event details | ❌ Never | Internal data |
| Client information | ❌ Never | Internal data |
| Crew details | ❌ Never | Internal data |
| Financial data | ❌ Never | Internal data |
| Damage/repair history | ⚠️ Selective | Owner decides what condition info to expose |
---
## Related Documentation
- [[00 - System Overview]] — High-level system overview
- [[01 - Inventory Management]] — Asset data that gets federated
- [[05 - Barcode and QR Scanning]] — Scanning federated assets
- [[07 - Technical Requirements]] — Deployment and security considerations

258
Test/EventKit/05 - Barcode and QR Scanning.md Normal file
View File

@@ -0,0 +1,258 @@
---
tags:
- eventkit
---
# Barcode & QR Scanning
## Purpose
Enable fast, accurate equipment tracking through QR code scanning. Every [[01 - Inventory Management|asset]], [[01 - Inventory Management#Cases & Packing|case]], and [[01 - Inventory Management#Warehouse & Locations|warehouse location]] gets a scannable code, powering workflows from check-out to stocktake to cross-company [[01 - Inventory Management#Sub-hire Management|sub-hire]].
---
## What Gets a Code
| Entity | Code Type | Encoded Data | Printed On |
| ---------------------- | ------------------ | ---------------------------------------- | ---------------------------------- |
| **Individual Asset** | QR Code | URL → `https://{instance}/asset/{uuid}` | Durable label sticker on the asset |
| **Flight Case** | QR Code | URL → `https://{instance}/case/{uuid}` | Case lid label / hang tag |
| **Warehouse Location** | QR Code | URL → `https://{instance}/location/{id}` | Shelf / bay / rack label |
| **Kit / Set** | QR Code (optional) | URL → `https://{instance}/kit/{id}` | Kit card / bag tag |
| **Consumable** | Barcode (EAN/UPC) | Product ID or manufacturer barcode | Existing packaging or custom label |
---
## QR Code Design
### Data Format
Each QR code encodes a **URL** pointing to the owning instance:
```
https://inventory.company-a.com/asset/550e8400-e29b-41d4-a716-446655440000
```
### Why URLs?
| Benefit | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| **Universal** | Any phone camera can scan it and open the asset page in a browser |
| **Federation-friendly** | The domain tells any EventKit instance who owns the asset (see [[04 - Federation Architecture#Global Asset Identity | Global Asset Identity]]) |
| **App-aware** | A dedicated EventKit app can intercept the URL and handle it natively |
| **Offline-capable** | The app can extract the UUID locally and sync the action later |
| **Future-proof** | No proprietary encoding — standard URLs work forever |
### Label Design
```
┌─────────────────────────────┐
│ ┌───────────┐ │
│ │ │ SM58-00142 │
│ │ QR Code │ Shure SM58 │
│ │ │ │
│ └───────────┘ Company A │
│ │
│ ID: 550e8400... │
└─────────────────────────────┘
```
Labels should include:
- **QR code** (primary)
- **Human-readable ID** (e.g. `SM58-00142`)
- **Product name**
- **Company name** (important for sub-hired equipment)
- **Optional**: Barcode (Code 128) as fallback
### Label Requirements
| Requirement | Details |
| ----------------- | ------------------------------------------------------------------------- |
| **Durability** | Laminated or heavy-duty vinyl — must survive road use, rain, and handling |
| **Size** | Minimum 30×30mm for QR code to ensure reliable scanning |
| **Adhesive** | Strong permanent adhesive for assets; removable for temporary labels |
| **Print quality** | Minimum 300 DPI for reliable scanning |
---
## Scanning Hardware
| Option | Best For | Notes |
| ----------------------------- | ----------------------------- | ---------------------------------------------------------- |
| **Phone camera (PWA)** | Occasional use, small teams | Zero hardware cost, works on any modern phone |
| **Phone camera (native app)** | Regular use | Better scanning speed, offline support, push notifications |
| **Bluetooth barcode scanner** | Warehouse ops, bulk scanning | Pairs with phone/tablet — much faster than camera |
| **Rugged handheld** | Heavy warehouse / outdoor use | e.g. Zebra TC-series — built-in scanner, drop-resistant |
| **Fixed scanner** | Check-in/check-out desk | Mounted scanner at warehouse dispatch point |
### Recommended Setup
| Role | Device |
| --------------------- | -------------------------------------------- |
| **Warehouse staff** | Bluetooth scanner + tablet (mounted on cart) |
| **On-site crew** | Phone app (PWA or native) |
| **Office / planning** | Web UI (no scanning needed) |
| **Dispatch desk** | Fixed USB scanner + desktop |
---
## Scanning Workflows
### Check-Out (Dispatch to Event)
```mermaid
sequenceDiagram
participant User as Warehouse Staff
participant App as EventKit App
participant API as API Server
User->>App: Open [[02 - Planning Module#Pull Lists / Equipment Planning|Event Pull List]]
App-->>User: Show items to dispatch
loop For each item/case
User->>App: Scan QR code
App->>API: POST /scan/checkout {asset_uuid, event_id}
API-->>App: ✅ Asset status → "[[01 - Inventory Management#Asset Lifecycle & Statuses|Checked Out]]"
App-->>User: ✅ Item confirmed on list
end
App-->>User: Pull list complete: 47/47 items scanned
```
### Check-In (Return from Event)
```mermaid
sequenceDiagram
participant User as Warehouse Staff
participant App as EventKit App
participant API as API Server
User->>App: Open Event Return
loop For each returning item
User->>App: Scan QR code
App-->>User: Prompt: Condition? [OK / Damaged]
User->>App: Select condition + optional note/photo
App->>API: POST /scan/checkin {asset_uuid, condition, notes}
API-->>App: ✅ Asset status → "Checked In" or "Damaged"
end
App-->>User: Return complete. 2 items flagged as damaged.
```
### Stocktake / Audit
```mermaid
sequenceDiagram
participant User as Warehouse Staff
participant App as EventKit App
participant API as API Server
User->>App: Start Stocktake for Location "Shelf B3"
User->>App: Scan location QR code
loop For each item on shelf
User->>App: Scan asset QR code
App->>API: POST /scan/stocktake {asset_uuid, location_id}
API-->>App: ✅ Asset found at expected location
end
App->>API: POST /stocktake/complete {location_id}
API-->>App: Report: 3 missing, 1 unexpected item found
App-->>User: Stocktake discrepancy report
```
### Case Packing
```mermaid
sequenceDiagram
participant User as Warehouse Staff
participant App as EventKit App
participant API as API Server
User->>App: Scan Case QR code
App-->>User: Show case contents (expected packing list)
loop For each item going into case
User->>App: Scan asset QR code
App->>API: POST /scan/pack {asset_uuid, case_uuid}
API-->>App: ✅ Item added to case
end
App-->>User: Case packed: 8/8 items ✅
```
### Sub-hire Receive (Federated)
```mermaid
sequenceDiagram
participant User as Company B Staff
participant B_App as Company B App
participant B_API as Company B API
participant A_API as Company A API
User->>B_App: Scan QR code on received item
Note over B_App: URL domain = company-a.com → [[04 - Federation Architecture|federated asset]]
B_App->>B_API: POST /scan/subhire-receive {url, condition}
B_API->>A_API: GET /federation/asset/{uuid}
A_API-->>B_API: Asset details (Shure SM58, SN: 00142)
B_API->>A_API: POST /federation/asset/{uuid}/checkin
B_API-->>B_App: ✅ Sub-hired asset received from Company A
B_App-->>User: Show asset details + "Owned by Company A"
```
### Quick Lookup
Scan any QR code outside of a workflow to instantly see:
- Asset/case details (model, serial, owner)
- Current status ([[01 - Inventory Management#Asset Lifecycle & Statuses|available, checked out, in repair]], etc.)
- Current [[01 - Inventory Management#Warehouse & Locations|location]]
- Current [[02 - Planning Module|event]] assignment (if any)
- Condition notes
- [[01 - Inventory Management#Maintenance & Testing|Maintenance]] due dates
---
## Label Printing
### Built-in Label Generation
| Feature | Description |
| --------------------- | -------------------------------------------------------------- |
| Single label printing | Generate and print a label for one asset |
| Bulk label printing | Generate labels for a batch of assets (e.g. all new purchases) |
| Case labels | Larger format labels for flight case lids |
| Location labels | Labels for warehouse shelves/bays/racks |
| Label templates | Customisable label layouts |
| Export formats | PDF (for any printer), ZPL (for Zebra label printers) |
### Label Printer Recommendations
| Printer | Use Case | Label Width |
| --------------------- | ----------------------- | ----------- |
| **Brother QL-series** | Office / low volume | 12–62mm |
| **Dymo LabelWriter** | Office / low volume | 19–54mm |
| **Zebra ZD-series** | Warehouse / high volume | 25–108mm |
| **Zebra ZQ-series** | Mobile / on-site | 48–72mm |
---
## Offline Scanning
| Scenario | Behaviour |
| ----------------------- | ----------------------------------------------------------- |
| **No connectivity** | Scans are queued locally on the device |
| **Weak connectivity** | Scans are queued and sent in batches when signal improves |
| **Back online** | Queued scans sync to the server with original timestamps |
| **Conflict resolution** | Server timestamps win; user is notified of any conflicts |
| **Local asset cache** | App caches asset data for offline lookup after initial sync |
---
## Related Documentation
- [[00 - System Overview]] — High-level system overview
- [[01 - Inventory Management]] — Assets and cases that get scanned
- [[04 - Federation Architecture]] — Scanning federated assets
- [[07 - Technical Requirements]] — Hardware and deployment considerations

185
Test/EventKit/06 - Module Integration.md Normal file
View File

@@ -0,0 +1,185 @@
---
tags:
- eventkit
---
# Module Integration
## Purpose
This document describes how the three core modules ([[01 - Inventory Management|Inventory]], [[02 - Planning Module|Planning]], [[03 - CRM Module|CRM]]) work together, including the key cross-module workflows and the unified features that span all modules.
---
## Integration Map
```mermaid
graph LR
subgraph CRM
Client["Client"]
Deal["Deal"]
Quote["Quote"]
end
subgraph Planning
Event["Event"]
PullList["Pull List"]
Crew["Crew"]
Transport["Transport"]
end
subgraph Inventory
Catalogue["Product Catalogue"]
Assets["Assets"]
Availability["Availability Engine"]
Cases["Cases"]
end
Client -->|"requests event"| Deal
Deal -->|"generates"| Quote
Quote -->|"references products from"| Catalogue
Quote -->|"checks"| Availability
Deal -->|"won → creates"| Event
Event -->|"has"| PullList
PullList -->|"reserves"| Assets
PullList -->|"checks"| Availability
Event -->|"books"| Crew
Event -->|"arranges"| Transport
Assets -->|"packed into"| Cases
Cases -->|"loaded onto"| Transport
Event -->|"closes → final costs to"| Deal
```
---
## Key Cross-Module Workflows
### 1. Enquiry to Event (CRM → Planning → Inventory)
| Step | Module | Action |
| ---- | --------- | --------------------------------------------------------------------------------- |
| 1 | CRM | Client enquiry received → Lead created |
| 2 | CRM | Lead qualified → Deal created with dates and venue |
| 3 | CRM | Sales rep builds a Quote using products from the **Inventory catalogue** |
| 4 | Inventory | **Availability engine** confirms stock for requested dates |
| 5 | CRM | Quote sent to client |
| 6 | CRM | Client accepts → Deal marked as "Won" |
| 7 | Planning | **Event auto-created** from the deal, with pull list pre-populated from the quote |
| 8 | Inventory | Equipment **reserved** for the event dates |
### 2. Event Execution (Planning → Inventory)
| Step | Module | Action |
| ---- | --------- | ----------------------------------------------------------------- |
| 1 | Planning | Event moves to "Prep" phase |
| 2 | Inventory | Warehouse team receives **pull list** for prep |
| 3 | Inventory | Equipment pulled, tested, **packed into cases** (via scanning) |
| 4 | Planning | Cases assigned to **truck pack** with weight/volume |
| 5 | Inventory | Equipment **checked out** (status: Checked Out) via scanning |
| 6 | Planning | Event status: "Load-Out" → "On-Site" |
| 7 | Planning | Event completes → "Load-In" (return) |
| 8 | Inventory | Equipment **checked in** with condition inspection (via scanning) |
| 9 | Inventory | Damaged items flagged → **repair workflow** triggered |
| 10 | Inventory | Equipment **re-shelved** → status: Available |
### 3. Sub-hire Flow (Planning → Inventory → Federation)
| Step | Module | Action |
| ---- | --------- | ------------------------------------------------------------------- |
| 1 | Planning | Pull list shows **shortage** — not enough stock |
| 2 | Inventory | System suggests **sub-hire** from federated partners |
| 3 | Inventory | **Availability query** sent to partner instances via federation |
| 4 | Inventory | Partner confirms availability → **Sub-hire request** sent |
| 5 | Inventory | Partner dispatches equipment |
| 6 | Inventory | Equipment received — **scanned in** with federated asset resolution |
| 7 | Planning | Sub-hired items added to event pull list |
| 8 | Planning | Event completes |
| 9 | Inventory | Sub-hired items **scanned out** → returned to partner |
| 10 | Inventory | Partner confirms receipt via federation |
| 11 | CRM | Sub-hire costs added to event financials |
### 4. Event Close-out (Planning → CRM → Inventory)
| Step | Module | Action |
| ---- | --------- | ------------------------------------------------------------------------------- |
| 1 | Planning | All equipment returned and inspected |
| 2 | Planning | Event status → "Closed" |
| 3 | Planning | **Final costs calculated**: equipment, crew hours, transport, sub-hire, damages |
| 4 | CRM | Costs flow to the deal → **profit/loss analysis** |
| 5 | CRM | **Invoice generated** from final costs |
| 6 | Inventory | Any **damage costs** attributed to the event for reporting |
---
## Unified Features
### Unified Dashboard
A single home screen showing:
| Widget | Source Module | Shows |
| ------------------------- | ------------- | ------------------------------------------- |
| **Upcoming Events** | Planning | Next 7 days of events with status |
| **Pipeline Value** | CRM | Total weighted pipeline value |
| **Equipment Utilisation** | Inventory | % of equipment currently deployed |
| **Stock Alerts** | Inventory | Low stock, overdue returns, maintenance due |
| **Crew Availability** | Planning | Available vs. booked crew this week |
| **Recent Activity** | All | Latest actions across the system |
### Unified Search
Search across all modules from a single search bar:
- **Contacts & companies** (CRM)
- **Events & projects** (Planning)
- **Products & assets** (Inventory)
- **Cases & locations** (Inventory)
- **Crew members** (Planning)
### Unified Activity Feed
A cross-module activity stream showing:
```
📋 Deal "Summer Festival 2026" → Won (CRM)
📦 Event "Summer Festival" auto-created with 142 line items (Planning)
🔒 48× L-Acoustics K2 reserved for June 14-18 (Inventory)
👤 3 crew members assigned: John (Sound), Lisa (Lighting) (Planning)
🚛 Truck pack created: 2× trucks, 4.2 tonnes (Planning)
⚠️ Shortage: 4× moving heads — sub-hire suggested (Inventory)
🤝 Sub-hire request sent to Partner Co. (Federation)
```
### Unified Notifications
| Notification | Trigger | Recipient |
| ------------------------- | ----------------------------------------- | -------------------- |
| New enquiry received | Lead created in CRM | Sales team |
| Quote accepted | Deal status → Won | Planning team |
| Equipment shortage | Pull list exceeds stock | Inventory manager |
| Maintenance due | Service date approaching | Warehouse manager |
| Sub-hire request received | Federation request from partner | Inventory manager |
| Event tomorrow | Event date is tomorrow | Assigned crew |
| Overdue return | Equipment not checked in by expected date | Warehouse + planning |
| Damage reported | Item flagged during check-in | Inventory manager |
### Unified Reporting
| Report | Spans |
| --------------------- | -------------------------------------------------------------- |
| Event profitability | Planning + CRM + Inventory (all costs vs. revenue) |
| Client lifetime value | CRM + Planning (revenue over time per client) |
| Equipment ROI | Inventory + Planning (revenue generated vs. cost of ownership) |
| Seasonal analysis | All (demand patterns across months/quarters) |
| Capacity planning | Inventory + Planning (can we handle upcoming bookings?) |
---
## Related Documentation
- [[00 - System Overview]] — High-level system overview
- [[01 - Inventory Management]] — Equipment and availability
- [[02 - Planning Module]] — Events and scheduling
- [[03 - CRM Module]] — Clients and pipeline
- [[04 - Federation Architecture]] — Cross-company flows
- [[05 - Barcode and QR Scanning]] — Scanning workflows powering check-in/out

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

108
Test/EventKit/08 - Open Questions.md Normal file
View File

@@ -0,0 +1,108 @@
---
tags:
- eventkit
---
# Open Questions
## Purpose
Remaining decisions and questions that need answers before or during implementation. Organised by topic area. See [[07 - Technical Requirements]] for decisions already made.
---
## Business & Scope
| # | Question | Options / Notes |
| --- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| 1 | **Primary equipment types** — which sectors will be supported first? | Audio, lighting, video, staging, rigging, power, furniture, décor — prioritise for MVP |
| 2 | **Target company size** — small (1-5 people) or larger (20+)? | Affects complexity of RBAC, approval workflows, and UI |
| 3 | **Pricing model** — how will EventKit itself be offered? | Open source, freemium, paid self-hosted licence, or SaaS alongside self-hosted? |
| 4 | **MVP scope** — which module to build first? | Inventory + Scanning → Planning → CRM → Federation is a natural order |
| 5 | **Data migration** — what systems are companies migrating from? | Spreadsheets, Rentman, Current RMS, HireHop, custom systems — affects import tooling |
---
## Technical
| # | Question | Options / Notes |
| --- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| 6 | ~~**Tech stack** — backend language and framework?~~ | ✅ **Decided: Go** with ConnectRPC |
| 7 | **Frontend framework** | React, Vue, Svelte, SolidJS? PWA vs native mobile app? (ConnectRPC generates typed TS clients for any framework) |
| 8 | ~~**Database**~~ | ✅ **Decided: PostgreSQL 15+** |
| 9 | **Search engine** | Built-in DB search, or dedicated (Meilisearch, Typesense) for large catalogues? |
| 10 | **File storage** | Local filesystem, S3-compatible, or both? |
| 11 | **Real-time updates** | gRPC server-streaming (via ConnectRPC) is the natural choice. SSE fallback for browsers? |
| 12 | **Background jobs** | Go goroutines + internal queue, or external (Redis, NATS)? |
---
## Federation
| # | Question | Options / Notes |
| --- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| 13 | **Discovery** — how do companies find each other? | Public directory, manual URL exchange, QR code handshake, or invitation link? |
| 14 | ~~**Protocol format**~~ | ✅ **Decided: gRPC via ConnectRPC** with Protobuf service definitions |
| 15 | **Pricing in federation** — should sub-hire rates be shared automatically? | Or negotiate out-of-band and just track the equipment movement? |
| 16 | **Asset ownership transfer** — can an asset be permanently sold to another instance? | Or only sub-hire (temporary)? |
| 17 | **Federation versioning** — how to handle protocol upgrades? | Protobuf's built-in backward compatibility helps here |
| 18 | **Dispute resolution** — what happens if companies disagree about asset condition? | Photo evidence at dispatch/return, timestamped condition logs |
---
## Scanning & Hardware
| # | Question | Options / Notes |
| --- | ------------------------------------------------------------------ | ------------------------------------------------------------ |
| 19 | **Primary scanning device** — phone cameras or dedicated scanners? | Phones (lower cost) vs. Bluetooth scanners (faster) vs. both |
| 20 | **Label printer** — should EventKit support direct printing? | Or generate PDFs and let users print on any printer? |
| 21 | **Existing barcodes** — do companies already have asset labels? | Need import/migration path for existing barcode schemes |
| 22 | **Offline requirements** — how often will users be offline? | Determines investment in offline-first architecture |
---
## CRM
| # | Question | Options / Notes |
| --- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| 23 | **Invoicing depth** — full invoicing or integration with existing accounting? | Full = more work but self-contained; integration = less reinvention |
| 24 | **Accounting integrations** — which platforms? | Xero, QuickBooks, FreshBooks, DATEV — prioritise for target market |
| 25 | **Email integration** — built-in email or link to external? | IMAP/SMTP integration vs. Gmail/Outlook API vs. just logging |
| 26 | **Marketing features** — email campaigns needed? | Or leave marketing to dedicated tools (Mailchimp, etc.)? |
---
## Planning
| # | Question | Options / Notes |
| --- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| 27 | **Crew management depth** — basic assignment or full scheduling? | Basic: assign people to events. Full: shifts, timesheets, payroll integration |
| 28 | **Transport planning** — basic or advanced? | Basic: assign vehicles. Advanced: route optimisation, weight distribution |
| 29 | **Venue database** — shared across instances? | Could be a federated feature — shared venue specs across the network |
| 30 | **Calendar integration** — which platforms? | Google Calendar, Outlook/Exchange, CalDAV — for crew and event sync |
---
## Priority Matrix
Suggested priority for answering these questions:
| Priority | Questions | Reason |
| -------------------------------------- | ------------------------------ | ------------------------------------------------- |
| ✅ **Answered** | 6, 8, 14 | Go, PostgreSQL, ConnectRPC/gRPC |
| 🔴 **Must answer before starting** | 1, 4, 7 | Scope and frontend framework |
| 🟡 **Answer during early development** | 2, 3, 9, 10, 11, 19, 23 | Affects architecture but can be deferred slightly |
| 🟢 **Answer before beta** | 5, 12, 13, 15-18, 20-22, 24-30 | Important but not blocking initial development |
---
## Related Documentation
- [[00 - System Overview]] — High-level system overview
- [[01 - Inventory Management]] — Inventory module design
- [[02 - Planning Module]] — Planning module design
- [[03 - CRM Module]] — CRM module design
- [[04 - Federation Architecture]] — Federation protocol design
- [[05 - Barcode and QR Scanning]] — Scanning and hardware
- [[06 - Module Integration]] — Cross-module workflows
- [[07 - Technical Requirements]] — Technical decisions made and remaining

154
Test/Inventory Management Tool.md Normal file
View File

@@ -0,0 +1,154 @@
# Chat Conversation
Note: _This is purely the output of the chat conversation and does not contain any raw data, codebase snippets, etc. used to generate the output._
### User Input
I want to develop an inventory management, planning and crm tool. Can you provide me with a detailed set of questions and featured one might integrate.
### Planner Response
# Inventory Management, Planning & CRM Tool — Discovery Questions & Feature Ideas
Below is a structured set of **discovery questions** to help define your requirements, followed by **feature suggestions** for each major module.
---
## 1. General / Cross-Cutting Questions
| # | Question |
|---|---------|
| 1 | **Who are the target users?** (e.g. small business, warehouse team, sales reps, managers) |
| 2 | **How many concurrent users** do you anticipate? |
| 3 | **Deployment model** — self-hosted, cloud SaaS, or hybrid? |
| 4 | **Multi-tenancy** — will multiple organisations share one instance? |
| 5 | **Tech stack preferences?** (e.g. Blazor/.NET, React/Node, Next.js, etc.) |
| 6 | **Mobile access** — responsive web, PWA, or native apps? |
| 7 | **Offline support** — do users need to work without connectivity? |
| 8 | **Existing systems to integrate with?** (accounting software, e-commerce platforms, ERP, email providers) |
| 9 | **Authentication** — SSO, OAuth, LDAP/AD, or simple email/password? |
| 10 | **Role-based access control** — what permission levels do you need? |
| 11 | **Internationalisation** — multi-language, multi-currency, timezone support? |
| 12 | **Regulatory / compliance needs?** (GDPR, industry-specific regulations) |
---
## 2. Inventory Management Module
### Discovery Questions
- How many **SKUs / products** do you manage?
- Do you have **multiple warehouses or locations**?
- Do you track inventory by **lot number, serial number, or expiry date**?
- Do you need **barcode / QR code** scanning?
- What **units of measure** do you use? Do items have conversions (e.g. box → unit)?
- Do you manage **raw materials, work-in-progress, and finished goods** (manufacturing)?
- How do you handle **returns, damages, and write-offs**?
- Do you need **automated reorder points / safety stock** calculations?
### Suggested Features
| Category | Features |
|----------|----------|
| **Product Catalogue** | SKU management, categories & tags, product variants (size/colour), images & attachments, custom attributes |
| **Stock Tracking** | Real-time stock levels per location, lot/serial tracking, expiry date tracking, stock valuation (FIFO/LIFO/weighted avg) |
| **Warehouse Ops** | Multi-warehouse support, bin/shelf locations, pick-pack-ship workflows, barcode/QR scanning, stock transfers between locations |
| **Purchasing** | Purchase orders, supplier management, automated reorder points, purchase approval workflows, goods receipt notes (GRN) |
| **Stock Adjustments** | Stocktake / cycle counts, write-offs & adjustments, damage tracking, audit trail for all movements |
| **Reporting** | Stock aging reports, turnover analysis, dead stock identification, ABC analysis, low-stock alerts & notifications |
---
## 3. Planning Module
### Discovery Questions
- What kind of **planning** do you need? (demand planning, production planning, project planning, resource planning)
- Do you use any **forecasting methods** today?
- Do you need **Gantt charts, Kanban boards**, or both?
- Are there **recurring tasks or schedules** to manage?
- Do you need **capacity planning** for teams or equipment?
- How do you currently handle **dependencies** between tasks?
- Do you need **budgeting and cost tracking** alongside planning?
### Suggested Features
| Category | Features |
|----------|----------|
| **Demand Planning** | Sales forecasting (historical trends, seasonal adjustments), demand signals from CRM pipeline, what-if scenario modelling |
| **Production / Procurement Planning** | BOM (Bill of Materials) explosion, MRP (Material Requirements Planning), lead time management, supplier capacity tracking |
| **Project / Task Management** | Kanban boards, Gantt charts, task dependencies & milestones, recurring tasks, time tracking, file attachments & comments |
| **Resource Planning** | Team workload view, equipment/asset scheduling, capacity vs demand visualisation, shift scheduling |
| **Budgeting** | Cost estimates per project/task, actual vs planned spend tracking, purchase requisition workflows |
| **Notifications** | Deadline reminders, overdue task alerts, milestone completion notifications, @mentions and collaboration |
---
## 4. CRM Module
### Discovery Questions
- What is your **sales process**? (B2B, B2C, or both?)
- How many **pipeline stages** do you typically have?
- Do you need **marketing automation** (email campaigns, lead scoring)?
- How do you **acquire leads** today? (website forms, referrals, cold outreach, trade shows)
- Do you need to track **customer support / service tickets**?
- What **communication channels** do you use? (email, phone, WhatsApp, live chat)
- Do you need **contract / subscription management**?
- How important is **reporting and analytics** on sales performance?
### Suggested Features
| Category | Features |
|----------|----------|
| **Contact Management** | Companies & contacts, contact segmentation & tags, interaction history (calls, emails, meetings), custom fields, duplicate detection |
| **Sales Pipeline** | Visual pipeline (drag-and-drop stages), deal value & probability, weighted pipeline forecasting, multiple pipelines, win/loss analysis |
| **Leads** | Lead capture (web forms, API), lead scoring, lead assignment rules, lead source tracking, conversion tracking |
| **Communication** | Email integration (send/receive from CRM), email templates, call logging, meeting scheduling, activity timeline |
| **Marketing** | Email campaigns & drip sequences, campaign ROI tracking, landing page builder, newsletter management |
| **Quotes & Invoicing** | Quote generation (linked to inventory/pricing), quote approval workflows, invoice creation, payment tracking |
| **Customer Support** | Ticket/case management, SLA tracking, knowledge base, customer satisfaction surveys |
| **Reporting** | Sales dashboards, rep performance metrics, conversion funnels, revenue forecasting, customer lifetime value |
---
## 5. Integration Between Modules
This is where the real power lies — connecting the three modules:
| Integration Point | Description |
|-------------------|-------------|
| **CRM → Inventory** | Checking real-time stock availability when creating quotes; auto-reserving stock for confirmed deals |
| **CRM → Planning** | Sales pipeline feeds demand forecasts; won deals auto-generate fulfilment tasks |
| **Inventory → Planning** | Low stock triggers purchase planning; demand forecasts drive reorder suggestions |
| **Planning → Inventory** | Production plans consume raw materials; task completion updates stock levels |
| **Unified Dashboard** | Single view combining sales pipeline value, stock health, and task progress |
| **Unified Search** | Search across contacts, products, and tasks from one search bar |
| **Activity Feed** | Cross-module activity stream (e.g. "Deal #102 won → Stock reserved → Fulfilment task created") |
---
## 6. Technical & Non-Functional Considerations
| Area | Questions / Features |
|------|---------------------|
| **API** | REST or GraphQL API for external integrations, webhooks for event-driven automation |
| **Import / Export** | CSV/Excel import for initial data migration, bulk export for reporting |
| **Audit Trail** | Full change history on all entities (who changed what, when) |
| **Notifications** | In-app, email, and push notifications; configurable per user |
| **Customisation** | Custom fields, custom views/filters, saved reports, workflow automation (if X then Y) |
| **Performance** | Pagination, caching strategy, background job processing for heavy operations |
| **Backup & Recovery** | Automated backups, point-in-time restore |
---
## Next Steps
Would you like me to:
1. **Deep-dive** into any specific module with more detailed requirements?
2. **Create a formal requirements document** or feature specification?
3. **Propose a tech stack and architecture** for building this?
4. **Build a prototype** of one of the modules to start iterating on?
Let me know which direction you'd like to take, and I'll tailor the next steps accordingly!