Technical Stack

This document describes the operating stack, development methodology, and architectural decisions behind Housecarl AuthZ.

Language: Rust

Housecarl is built entirely in Rust, chosen for:

• Memory safety without garbage collection - No null pointer exceptions, no data races, no buffer overflows
• Zero-cost abstractions - High-level code that compiles to efficient machine code
• Excellent async support - Native async/await with the Tokio runtime
• Strong type system - Catch errors at compile time, not in production

All services, libraries, and CLI tools are written in Rust. The only exceptions are test utilities (Go) and database migrations (SQL).

Runtime Environment

Containerization

Housecarl runs as containerized services:

• Base image: Debian 12.6-slim (minimal attack surface)
• Container format: OCI-compliant images
• Orchestration: Kubernetes-native deployment
• No external runtime dependencies: Statically linked binaries with rustls (no OpenSSL)

Database

• PostgreSQL 17 - ACID-compliant relational database
• Schema-per-tenant isolation - Each tenant's data is physically separated at the database level
• Custom migration system - The udr_db framework handles schema versioning per service

Architecture

Centralized Authorization Service

Housecarl follows a centralized authorization architecture:

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ Web Browser │───▶│ housecarl-ui│───▶│   Envoy     │
│             │    │   (Web UI)  │    │ gRPC Gateway│
└─────────────┘    └─────────────┘    └─────────────┘
                         │                   │
                         │                   ▼
┌─────────────┐          │            ┌─────────────┐
│   CLI       │──────────┼───────────▶│ housecarl   │
│ (housectl)  │          │            │ (authz core)│
└─────────────┘          │            └─────────────┘
                         │                   │
                         ▼                   │
                  ┌─────────────┐            │
                  │   billing   │◀───────────┘
                  │  service    │
                  └─────────────┘
                         │
                         ▼
                  ┌─────────────┐
                  │   audit     │
                  │  service    │
                  └─────────────┘

All authorization decisions flow through the central housecarl service. This design provides:

• Single source of truth for all access control decisions
• Consistent policy enforcement across all entry points
• Complete audit trail of every authorization decision
• Simplified integration - one API for all authorization needs

gRPC Communication

Internal service communication uses gRPC (HTTP/2 + Protocol Buffers):

• High performance - Binary serialization, multiplexed connections
• Strong typing - Protocol buffer schemas enforce API contracts
• Streaming support - Bi-directional streaming for real-time updates
• Language agnostic - Easy integration from any language with gRPC support

External access is available via:

• REST/JSON - Envoy gRPC-JSON transcoding for HTTP clients
• Native gRPC - Direct gRPC for maximum performance

Service Responsibilities

Service	Responsibility
housecarl	Core authorization engine, JWT authentication, policy evaluation
housecarl-ui	Web interface, OAuth2 flows, email signup
billing	Stripe integration, subscription management, usage tracking
audit	Centralized audit logging, compliance reporting

Development Methodology

Test-Driven Development (TDD)

All Housecarl development follows strict TDD:

1. Write failing test first - Define expected behavior before implementation
2. Minimal implementation - Write just enough code to pass the test
3. Refactor - Improve code quality while keeping tests green

Build System

Development uses a two-tier build system:

• Cargo - Fast iteration during development (cargo check, cargo test)
• Bazel - Hermetic, reproducible builds for CI/CD and production

Bazel provides:

• Remote caching for fast builds across the team
• Hermetic builds that work identically everywhere
• Fine-grained dependency tracking in the monorepo

Quality Gates

Every change must pass:

• Unit tests (Rust)
• Integration tests
• Linting (cargo clippy with zero warnings)
• Formatting (cargo fmt)
• Full repository build (./bzsh test //...)

Security Design

Authentication

• JWT tokens - Stateless authentication with tenant context embedded
• Argon2 password hashing - Memory-hard algorithm resistant to GPU attacks
• OAuth2/OIDC - Google SSO with extensible provider framework

TLS/SSL

• rustls - Pure Rust TLS implementation (no OpenSSL dependency)
• Modern cipher suites only - TLS 1.2+ with strong ciphers
• Certificate validation - Strict certificate chain verification

Data Protection

• Parameterized queries - All database access uses prepared statements
• Input validation - All external input validated at service boundaries
• Secrets management - Credentials via environment variables, never in config files

Observability

Metrics

All services expose Prometheus metrics:

• Request counts, latencies, error rates
• Database query performance
• gRPC method statistics

Logging

Structured logging via the tracing crate:

• JSON-formatted logs for machine parsing
• Correlation IDs across service boundaries
• Configurable log levels per component

Tracing

Distributed tracing with Jaeger:

• End-to-end request visualization
• Latency analysis across services
• Bottleneck identification

Key Dependencies

Category	Library	Purpose
HTTP Server	Axum	Async web framework with Tower middleware
gRPC	Tonic	gRPC server and client
Database	sqlx	Async PostgreSQL with compile-time query checking
Async Runtime	Tokio	Industry-standard async runtime
Serialization	serde	JSON/TOML serialization
Authentication	jwt-simple	JWT token handling
Password Hashing	argon2	Secure password storage
Templating	Askama	Compile-time type-safe HTML templates

Why This Stack?

The technology choices reflect Housecarl's core values:

1. Reliability - Rust's safety guarantees prevent entire classes of bugs
2. Performance - Zero-cost abstractions and native async for high throughput
3. Security - Memory safety, rustls, and defense-in-depth architecture
4. Operability - Comprehensive observability and Kubernetes-native deployment
5. Maintainability - Strong types, TDD, and monorepo structure for long-term health

This stack enables Housecarl to deliver enterprise-grade authorization that you can trust with your most sensitive access control decisions.