Main X Service

@agents/share/overview.md

Subprojects

Subprojects are grouped one directory per entity. Each entity directory holds a front-end web app, a matcher (or verifier) library crate, a service API crate, and entity-level spec/ + AGENTS/ umbrella docs.

Entity	Service	Library	Front-end	Umbrella
Person	person-service-with-loco	person-matcher-rust-crate	person-front-end-with-svelte	spec
Worker	worker-service-with-loco	worker-matcher-rust-crate	worker-front-end-with-svelte	spec
Place	place-service-with-loco	place-matcher-rust-crate	place-front-end-with-svelte	spec
Thing	thing-service-with-loco	thing-matcher-rust-crate	thing-front-end-with-svelte	spec
Event	event-service-with-loco	event-matcher-rust-crate	event-front-end-with-svelte	spec
Course	course-service-with-loco	course-matcher-rust-crate	course-front-end-with-svelte	spec
Organization	organization-service-with-loco	organization-matcher-rust-crate	organization-front-end-with-svelte	spec
Care pathway	care-pathway-service-with-loco	care-pathway-matcher-rust-crate	care-pathway-front-end-with-svelte	spec
Authentication	authentication-service-with-loco	authentication-verifier-rust-crate	authentication-front-end-with-svelte	spec

Each crate is self-contained: it owns its REST API, its persistence schema, and its matching algorithm. They share an architecture and a documentation layout, not code.

What every crate does

• CRUD on its entity with soft delete and an audit trail
• Probabilistic + deterministic matching with weighted, configurable scoring
• Full-text search via Tantivy (fuzzy, phonetic where applicable)
• Duplicate detection real-time on create and via batch deduplicate scans
• Record merging with link tracking and a transferred-data snapshot
• Data validation at the create/update boundary (returns 422 on failure)
• Privacy controls — per-field masking, GDPR export, consent records
• Event streaming of CRUD operations
• REST API (Axum) with OpenAPI/Swagger
• gRPC stub (Tonic) for high-throughput callers
• Observability — tracing + OpenTelemetry OTLP

See agents/share/rust-loco-stack.md for the full dependency inventory.

Running

From any subproject root:

# REST + gRPC API
cargo run --release

# Tests
cargo test --lib

# Benchmarks (where available)
cargo bench

Documentation

Top-level reference docs in agents/share/:

File	Purpose
overview.md	High-level project overview
architecture.md	Layered architecture
rust-loco-stack.md	Full Rust + Loco dependency stack
loco.md	Loco framework (backend-only conventions)
match-search-merge.md	Match / search / merge workflows
match.md	Matching algorithms
search.md	Search (Tantivy)
merge.md	Merge workflow
dataflow.md	Create / search / merge data flows
privacy.md	Masking, GDPR, consent
auditability.md	Audit logging + event streaming
availability.md	Health, scaling
observability.md	Tracing + OpenTelemetry (summary)
rust-tracing-opentelemetry-stack.md	Tracing + OpenTelemetry (full)
restful.md	REST API conventions
postgresql.md	PostgreSQL setup
locales.md	i18n & l10n
compliance-for-healthcare.md	HIPAA, NHS, …
compliance-for-technology.md	ISO, GDPR, …

Per-crate reference docs live in <crate>/AGENTS/:

• index.md — directory of the crate's local docs
• models.md — domain model reference
• matching.md — per-crate matching tuning
• restful.md — REST API surface
• testing.md — test layout

Architecture snapshot

┌─────────────────────────────────────────────────────────────┐
│ Client (curl / SDK / gRPC client)                           │
└────────────────────────────┬────────────────────────────────┘
                             │
            ┌────────────────▼────────────────┐
            │ REST API (Axum) + gRPC (Tonic)  │
            │ + OpenAPI/Swagger UI            │
            │ /api/<plural>/…                 │
            └────────────────┬────────────────┘
                             │
            ┌────────────────▼────────────────┐
            │ Application logic               │
            │  • Validation & normalization   │
            │  • Matching (probabilistic +    │
            │     deterministic)              │
            │  • Privacy (masking, GDPR)      │
            │  • Audit log emission           │
            └────────────────┬────────────────┘
                             │
        ┌────────────────────┼─────────────────────┐
        │                    │                     │
┌───────▼──────┐    ┌────────▼────────┐   ┌────────▼────────┐
│ PostgreSQL   │    │ Tantivy index   │   │ Event stream    │
│ (SeaORM)     │    │ (full-text +    │   │ (Fluvio /       │
│              │    │  fuzzy/phonetic)│   │  in-memory)     │
└──────────────┘    └─────────────────┘   └─────────────────┘

Status

Backend-only Rust services. All crates compile cleanly and pass their lib tests.

License

Each crate is multi-licensed; see the individual Cargo.toml for terms.