From 682ccd774bf689cfb17f619ea32acedbead5985c Mon Sep 17 00:00:00 2001 From: KoCoder Date: Thu, 26 Feb 2026 21:47:14 +0100 Subject: [PATCH] vault backup: 2026-02-26 21:47:14 --- Test/EventKit/00 - System Overview.md | 118 ++++++ Test/EventKit/01 - Inventory Management.md | 186 +++++++++ Test/EventKit/02 - Planning Module.md | 188 +++++++++ Test/EventKit/03 - CRM Module.md | 155 +++++++ Test/EventKit/04 - Federation Architecture.md | 393 ++++++++++++++++++ Test/EventKit/05 - Barcode and QR Scanning.md | 258 ++++++++++++ Test/EventKit/06 - Module Integration.md | 185 +++++++++ Test/EventKit/07 - Technical Requirements.md | 351 ++++++++++++++++ Test/EventKit/08 - Open Questions.md | 108 +++++ Test/Inventory Management Tool.md | 154 +++++++ 10 files changed, 2096 insertions(+) create mode 100644 Test/EventKit/00 - System Overview.md create mode 100644 Test/EventKit/01 - Inventory Management.md create mode 100644 Test/EventKit/02 - Planning Module.md create mode 100644 Test/EventKit/03 - CRM Module.md create mode 100644 Test/EventKit/04 - Federation Architecture.md create mode 100644 Test/EventKit/05 - Barcode and QR Scanning.md create mode 100644 Test/EventKit/06 - Module Integration.md create mode 100644 Test/EventKit/07 - Technical Requirements.md create mode 100644 Test/EventKit/08 - Open Questions.md create mode 100644 Test/Inventory Management Tool.md diff --git a/Test/EventKit/00 - System Overview.md b/Test/EventKit/00 - System Overview.md new file mode 100644 index 0000000..19ab67e --- /dev/null +++ b/Test/EventKit/00 - System Overview.md @@ -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 diff --git a/Test/EventKit/01 - Inventory Management.md b/Test/EventKit/01 - Inventory Management.md new file mode 100644 index 0000000..c0f8225 --- /dev/null +++ b/Test/EventKit/01 - Inventory Management.md @@ -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 diff --git a/Test/EventKit/02 - Planning Module.md b/Test/EventKit/02 - Planning Module.md new file mode 100644 index 0000000..2489806 --- /dev/null +++ b/Test/EventKit/02 - Planning Module.md @@ -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 diff --git a/Test/EventKit/03 - CRM Module.md b/Test/EventKit/03 - CRM Module.md new file mode 100644 index 0000000..54fa085 --- /dev/null +++ b/Test/EventKit/03 - CRM Module.md @@ -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 diff --git a/Test/EventKit/04 - Federation Architecture.md b/Test/EventKit/04 - Federation Architecture.md new file mode 100644 index 0000000..a7f775c --- /dev/null +++ b/Test/EventKit/04 - Federation Architecture.md @@ -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 diff --git a/Test/EventKit/05 - Barcode and QR Scanning.md b/Test/EventKit/05 - Barcode and QR Scanning.md new file mode 100644 index 0000000..1e79d78 --- /dev/null +++ b/Test/EventKit/05 - Barcode and QR Scanning.md @@ -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 diff --git a/Test/EventKit/06 - Module Integration.md b/Test/EventKit/06 - Module Integration.md new file mode 100644 index 0000000..5fa7cdf --- /dev/null +++ b/Test/EventKit/06 - Module Integration.md @@ -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 diff --git a/Test/EventKit/07 - Technical Requirements.md b/Test/EventKit/07 - Technical Requirements.md new file mode 100644 index 0000000..3ca91b7 --- /dev/null +++ b/Test/EventKit/07 - Technical Requirements.md @@ -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 diff --git a/Test/EventKit/08 - Open Questions.md b/Test/EventKit/08 - Open Questions.md new file mode 100644 index 0000000..7b3f0d9 --- /dev/null +++ b/Test/EventKit/08 - Open Questions.md @@ -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 diff --git a/Test/Inventory Management Tool.md b/Test/Inventory Management Tool.md new file mode 100644 index 0000000..69d31b4 --- /dev/null +++ b/Test/Inventory Management Tool.md @@ -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! \ No newline at end of file