Architecture Overview

Overview

BlocMarket is built entirely in Rust (edition 2024) as a 35-crate Cargo workspace. The architecture follows hexagonal (ports and adapters) principles with event sourcing foundations.

System Layers

┌─────────────────────────────────────────────┐
│              Client Layer                    │
│  Leptos WASM (Web)  ·  Tauri (Mobile)       │
├─────────────────────────────────────────────┤
│              API Layer                       │
│  Axum 0.8  ·  WebSocket  ·  GraphQL         │
├─────────────────────────────────────────────┤
│              Domain Layer                    │
│  31 library crates (hexagonal architecture)  │
├─────────────────────────────────────────────┤
│              Data Layer                      │
│  PostgreSQL 16 + PostGIS  ·  Redis 7        │
├─────────────────────────────────────────────┤
│              Infrastructure Layer            │
│  Docker  ·  K8s  ·  Cloudflare  ·  Stripe   │
└─────────────────────────────────────────────┘

Workspace Structure

bloc_market/
  apps/
    api/              # Axum HTTP/WebSocket API server
    web/              # Leptos WASM frontend (compiled via Trunk)
    mobile/           # Tauri v2 native shell (iOS/Android)
    gdpr-worker/      # Background GDPR data processing
  crates/
    core/             # Domain types, value objects, errors
    db/               # SQLx queries, migrations, repositories
    auth/             # JWT authentication, Argon2id hashing
    cache/            # Redis caching layer
    users/            # User management, profiles
    properties/       # Property CRUD, spatial search
    bids/             # Bid lifecycle management
    payments/         # Stripe integration, escrow
    transactions/     # Transaction milestone tracking
    assemblies/       # Bloc formation state machine
    notifications/    # Push notifications (FCM), in-app alerts
    monitoring/       # Prometheus metrics, alerting, health checks
    geospatial/       # PostGIS spatial queries, proximity search
    documents/        # Document management, DocuSign integration
    webhooks/         # HMAC-SHA256 webhook delivery
    events/           # Event sourcing foundations
    graphql_api/      # GraphQL API layer (async-graphql)
    i18n/             # Internationalization (8 locales)
    oauth2_server/    # OAuth 2.0 client credentials
    enterprise/       # Enterprise API key management
    whitelabel/       # White-label brand configuration
    compliance/       # GDPR, regulatory compliance
    openbanking/      # Open Banking payment flows
    valuation/        # Property valuation calculations
    observability/    # OpenTelemetry distributed tracing
    # ... and more

Key Design Decisions

Hexagonal Architecture

Domain logic lives in library crates with no framework dependencies. The api crate adapts Axum to domain ports. This enables testing domain logic without HTTP or database.

Event Sourcing Foundation

The events crate and event_store table provide append-only event logs. Events are immutable and replicate naturally via PostgreSQL logical replication, simplifying future multi-region deployment.

RBAC Model

Five roles with hierarchical access:

Role	Access
Admin	Full platform access
Moderator	User/content moderation
Homeowner	Property and bloc management
Developer	Development-related features
Tenant	Read-only + bidding

Row-Level Security (RLS) enforces access at the database level.

Real-time

WebSocket connections authenticate via JWT. Live bid updates, notification delivery, and bloc state changes stream to connected clients.

Expansion Products

Nine products across three categories, each with its own crate and route module:

Developers: Site Assembly, Rooftop Assembly, Nutrient Credits, SANOS, Section 106

Grid: BESS Sites, Edge Data Centers

Yield: Industrial Outdoor Storage, Telecom Leases

Feature flags control product availability per environment.

Quality Gates

Gate	Tool	Threshold
Formatting	rustfmt (edition 2024)	pass/fail
Linting	clippy (pedantic + nursery)	0 warnings
Unit Tests	cargo test	100% pass
Coverage	cargo-llvm-cov	>= 75% branch
Dependency Audit	cargo-deny	0 critical advisories
Secret Scanning	gitleaks	0 findings