Founder System View

Zenvee Platform Architecture

This page turns the documented architecture into a visual system map. It shows how the mobile app, API, data platform, realtime layer, financial records, audit trail, and founder visibility work together today, and how the platform is designed to grow without forcing a premature microservice split.

1 deployable backend today
4 observability streams tracked separately
6 core platform modules drive the marketplace
Option 2 PostgreSQL first, then Redis and specialized stores when justified

Whole Platform View

This is the high-level founder picture. Customers move from location-aware service discovery into curated technician matching, technician-card selection built around the kind of service experience they want, booking, live arrival coordination, and in-service visibility. The API stays as a modular monolith, while the platform keeps clear seams for payments, notifications, reporting, realtime delivery, and future scale upgrades.

System Map
flowchart TB Customer[Customer App\nlocation-aware discovery\nexperience-driver card selection]:::client Technician[Technician App\n.NET MAUI]:::client Admin[Founder or Admin Surface\nWeb or internal tools]:::client Customer --> Gateway Technician --> Gateway Admin --> Gateway subgraph Runtime[ASP.NET Core Modular Monolith] Gateway[API + Auth + OpenAPI]:::api Discovery[Discovery and matching workflow\nlocation\nservice intent\navailability\nfit ranking\ncard-ready experience driver]:::core Modules[Business Modules\nIdentity\nProfiles\nVerification\nTrust\nBooking\nAvailability\nPayments\nNotifications\nAdmin\nReporting]:::core Realtime[SignalR Realtime Layer\nbooking status\npresence\nlive arrival\nin-service location sharing]:::realtime Jobs[Background Jobs\ntimeouts\nretries\nrerouting\nsettlement tasks]:::ops Events[In-process Events\nworkflow fan-out]:::ops end Gateway --> Discovery Discovery --> Modules Modules --> Events Events --> Realtime Events --> Jobs subgraph Data[Data Platform Option 2] Pg[(PostgreSQL\ntransactional truth)]:::db Ledger[(Append-only records\nbooking events\naudit\nfinancial ledger\noutbox)]:::ledger Redis[(Redis later\npresence\nSignalR coordination\nhot state)]:::cache ReadSide[(Read-side or search later\noperator reporting\ndiscovery\nheavy filtering)]:::read Telemetry[(Telemetry store later\nGPS and time-series load)]:::telemetry end Modules --> Pg Modules --> Ledger Realtime -.scale when justified.-> Redis Modules -.read pressure.-> ReadSide Realtime -.telemetry pressure.-> Telemetry subgraph Visibility[Founder Visibility] Logs[Operational Logs]:::obs Audit[Audit Events]:::obs Metrics[Business Metrics]:::obs Sessions[Realtime Telemetry]:::obs end Events --> Logs Events --> Audit Events --> Metrics Realtime --> Sessions classDef client fill:#e8f1ff,stroke:#0f6cbd,color:#0f2445,stroke-width:1.5px; classDef api fill:#dff4ff,stroke:#0b4f8a,color:#0f2445,stroke-width:1.5px; classDef core fill:#eef7ea,stroke:#2f7d32,color:#173a1c,stroke-width:1.5px; classDef realtime fill:#fff2df,stroke:#d46b08,color:#5d3300,stroke-width:1.5px; classDef ops fill:#f4ecff,stroke:#6d28d9,color:#331759,stroke-width:1.5px; classDef db fill:#e6fbf6,stroke:#0f766e,color:#103b37,stroke-width:1.5px; classDef ledger fill:#fff0f3,stroke:#be185d,color:#53152b,stroke-width:1.5px; classDef cache fill:#fff8db,stroke:#a16207,color:#5b3900,stroke-width:1.5px; classDef read fill:#eef2ff,stroke:#4338ca,color:#24235f,stroke-width:1.5px; classDef telemetry fill:#edfdf7,stroke:#059669,color:#0e4c3e,stroke-width:1.5px; classDef obs fill:#f8f9fc,stroke:#64748b,color:#334155,stroke-width:1.2px;

What exists already

  • ASP.NET Core API host
  • Identity and role-based authorization
  • PostgreSQL-backed persistence
  • Structured logs with console and DB sinks

What is added next

  • curated technician matching and ranking
  • one technician-selected experience driver on each customer card
  • append-only booking events
  • audit events and financial ledger
  • transactional outbox
  • SignalR booking, arrival, and presence channels

Why founders care

The platform is being shaped so technician fit, customer experience choice, card positioning, operations, finance, live coordination, and compliance reassurance are explainable later without a rewrite.

How One Booking Moves Through The Platform

This is the refined customer and technician flow. It starts with service intent and technician fit, then moves through card-based technician choice, booking, acceptance, live arrival, and in-service coordination. It shows where the API, realtime updates, reliability records, and founder visibility all meet around one booking.

Booking Flow
sequenceDiagram autonumber participant C as Customer App participant M as Matching Workflow participant API as API Endpoint participant APP as Application Workflow participant DB as PostgreSQL participant OUT as Outbox participant RT as SignalR participant T as Technician App participant OPS as Founder Metrics and Audit C->>API: Share location, choose service, and desired technician experience API->>M: Request ranked technician options M->>APP: Apply trust, availability, service fit, distance, and experience-driver card rules APP->>DB: Read technician fit, availability, and current state DB-->>APP: Candidate technicians and booking constraints APP-->>M: Ranked technician choices with ETA, fit, and one experience driver per card M-->>API: Curated selection results API-->>C: Show technician cards with one experience driver and supporting details C->>API: Select technician or request best-match booking API->>APP: Validate user, trust, availability, and selection rules APP->>DB: Save booking current state APP->>DB: Append BookingEvent(booking.requested) APP->>DB: Append OutboxMessage DB-->>APP: Commit succeeds APP-->>API: Return booking created API-->>C: Booking request submitted APP->>RT: Push technician request and booking status update RT-->>T: Technician sees request with customer and service context T->>API: Accept, decline, or counter API->>APP: Apply transition rules APP->>DB: Update booking state APP->>DB: Append BookingEvent(booking.accepted or declined) APP->>DB: Append AuditEvent or FinancialLedgerEntry when needed APP->>DB: Append OutboxMessage APP->>RT: Push shared status update RT-->>C: Customer sees realtime booking state T->>RT: Share active arrival or in-service location updates when allowed RT-->>C: Customer sees live arrival or in-service coordination updates DB-->>OPS: Audit trail, metrics, and reporting become queryable
Matching ranks technicians by fit, availability, trust, ETA, and card strategy Current-state rows tell us what is true now Append-only records tell us how we got there SignalR tells connected users immediately during booking and arrival flow

Customer reassurance rule

Licensing and required compliance checks are handled as platform qualification gates first. Customers can still open booking detail or an on-demand credential view to confirm license and required proof when they want additional reassurance. The exact details shown should vary by jurisdiction, but the default trust view should cover active status, expiry context, and experience-building signals that help the customer feel confident.

Reliability, Observability, and Traceability

The platform is not relying on one giant log table. Operational logs, audit history, business metrics, and realtime telemetry are separated so finance, trust, support, and founder questions can be answered cleanly.

Visibility Model
flowchart LR Action[One business action\nexample: technician accepts booking]:::action --> Correlation[Shared correlation id]:::corr Correlation --> LogStream[Operational Logs\nrequests\nerrors\nperformance]:::stream Correlation --> AuditStream[Audit Events\nadmin and sensitive actions]:::stream Correlation --> MetricStream[Business Events and Metrics\nbookings\nresponse times\npayout health]:::stream Correlation --> TelemetryStream[Realtime Telemetry\npresence\nactive GPS sessions]:::stream LogStream --> Founder[Founder and Support Review]:::out AuditStream --> Founder MetricStream --> Founder TelemetryStream --> Founder classDef action fill:#e8f1ff,stroke:#0f6cbd,color:#17304d,stroke-width:1.5px; classDef corr fill:#fff8db,stroke:#a16207,color:#5b3900,stroke-width:1.5px; classDef stream fill:#f8f9fc,stroke:#64748b,color:#334155,stroke-width:1.4px; classDef out fill:#eef7ea,stroke:#2f7d32,color:#173a1c,stroke-width:1.5px;

Operational logs

Requests, failures, integrations, and background-job activity. Good for diagnosing runtime problems.

Audit events

Admin approvals, overrides, trust decisions, and financial adjustments. Good for founder and support review.

Business metrics

Booking funnel, technician response time, completion rates, payout status, and support-safe reporting.

Realtime telemetry

Presence and active-booking GPS sessions. Bounded retention, separate from normal logs, and tied to legitimate workflows.

Data Platform Responsibilities

Option 2 is not “many databases now.” It is “explicit responsibilities now, specialized stores when needed.” This diagram shows which store owns which kind of truth.

Store Roles
flowchart TD subgraph PG[PostgreSQL now] CurrentState[Current transactional truth\nidentity\nprofiles\nbookings\navailability\npayments]:::pg BookingEvents[Booking events\nappend only]:::pg AuditEvents[Audit events\nappend only]:::pg Ledger[Financial ledger\nappend only]:::pg Outbox[Outbox messages\nappend only]:::pg SessionMeta[Location session metadata\nbounded]:::pg end subgraph RedisLater[Redis when justified] Presence[Presence and connection hot state]:::redis Coordination[SignalR coordination and hot transient state]:::redis end subgraph ReadLater[Read-side or search later] Reporting[Operator reporting and founder read models]:::read Discovery[Technician discovery and heavy filtering]:::read end subgraph TelemetryLater[Telemetry store later] GPS[High-volume GPS or session telemetry]:::tele Timeseries[Time-series analytics and aggregates]:::tele end classDef pg fill:#e6fbf6,stroke:#0f766e,color:#103b37,stroke-width:1.4px; classDef redis fill:#fff8db,stroke:#a16207,color:#5b3900,stroke-width:1.4px; classDef read fill:#eef2ff,stroke:#4338ca,color:#24235f,stroke-width:1.4px; classDef tele fill:#edfdf7,stroke:#059669,color:#0e4c3e,stroke-width:1.4px;

Staged Upgrade Path

The platform is intentionally staged so the team can gain reliability and observability first, then add new infrastructure only when a measured workload makes it worthwhile.

Growth Path
1

Today

One deployable backend, PostgreSQL persistence, structured logs, auth, role-aware endpoints, and clean project boundaries.

2

Reliability pass

Add append-only booking events, audit events, financial ledger entries, correlation flow, and transactional outbox.

3

Realtime pass

Add SignalR for booking propagation, presence, and active-booking location sharing backed by jobs and in-process events.

4

Redis when justified

Add Redis for multi-instance SignalR coordination and hot presence state, not for financial or booking truth.

5

Specialized stores later

Add read-side/search or telemetry stores only when reporting, discovery, or GPS load starts competing with core transactions.

This founder view is derived from the current architecture, roadmap, backlog, decisions, and data-platform documents. It is meant to make the platform explainable as a whole, not to lock every low-level implementation detail in place too early.