Technical Architecture

Overview

The Hometown USA Real Estate (HURE) platform is built entirely on open source technologies. This document celebrates the incredible projects that power our mission to connect military families with trusted local real estate partners.

We believe in standing on the shoulders of giants—and giving credit where credit is due.

Architecture Diagram

┌─────────────────────────────────────────────────────────────────────────────┐
│                              HURE Platform                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐                   │
│  │   Browser   │────▶│    Caddy    │────▶│   Astro     │                   │
│  │   Client    │     │   Reverse   │     │   Static    │                   │
│  └─────────────┘     │   Proxy     │     │   Site      │                   │
│                      └──────┬──────┘     └─────────────┘                   │
│                             │                                               │
│                      ┌──────▼──────┐     ┌─────────────┐                   │
│                      │   FastAPI   │────▶│  SQLite +   │                   │
│                      │   Backend   │     │  sqlite-vec │                   │
│                      └──────┬──────┘     └─────────────┘                   │
│                             │                                               │
│        ┌────────────────────┼────────────────────┐                         │
│        │                    │                    │                         │
│  ┌─────▼─────┐       ┌─────▼─────┐       ┌─────▼─────┐                    │
│  │ Keycloak  │       │   Stripe  │       │  Ollama   │                    │
│  │   OIDC    │       │ Payments  │       │Embeddings │                    │
│  └───────────┘       └───────────┘       └───────────┘                    │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Frontend Stack

Astro 5

The web framework for content-driven websites

astro.build | GitHub

Astro powers our entire frontend with its revolutionary “Islands Architecture”—shipping zero JavaScript by default and hydrating only interactive components. For a content-heavy site with 3,222 county pages, this means blazing fast load times.

Why we love it:

• Zero-JS by default, partial hydration where needed
• Content Collections for type-safe markdown
• Built-in sitemap, RSS, and SEO support
• First-class MDX support for our feature documentation

// Our Astro config showcases modern web best practices
export default defineConfig({
  integrations: [react(), mdx(), icon()],
  site: 'https://hometownusarealestate.com',
});

React 19

The library for web and native user interfaces

react.dev | GitHub

React 19 powers our interactive components—the admin dashboard, map interface, and broker portal. Combined with Astro’s partial hydration, we get the best of both worlds: static speed with dynamic interactivity.

Key uses:

• Admin panel CRUD interfaces
• Interactive county map with Leaflet
• Real-time form validation
• TanStack Query for server state

Tailwind CSS 4

A utility-first CSS framework

tailwindcss.com | GitHub

Tailwind v4 brings CSS-first configuration and lightning-fast builds through the new Vite plugin. Our military-professional theme uses custom OKLCH colors for accessibility.

/* Our brand colors in global.css */
@theme {
  --color-hure-gold: oklch(0.75 0.15 85);
  --color-hure-navy: oklch(0.25 0.08 250);
  --color-hure-green: oklch(0.55 0.15 145);
}

shadcn/ui

Beautifully designed components built with Radix UI and Tailwind

ui.shadcn.com | GitHub

Not a component library—a collection of reusable components you own and customize. Every button, card, and dialog in HURE comes from shadcn/ui, giving us full control over the design system.

Components we use:

• Card, Badge, Button for consistent UI
• Dialog for modals and confirmations
• Select, Switch, Tabs for forms
• Command (cmdk) for quick search

Radix UI

Unstyled, accessible UI primitives

radix-ui.com | GitHub

The foundation under shadcn/ui. Radix provides WCAG-compliant primitives with proper ARIA attributes, keyboard navigation, and focus management out of the box.

Leaflet & React Leaflet

The leading open-source JavaScript library for interactive maps

leafletjs.com | GitHub

Our interactive county map uses Leaflet for rendering 3,222 US counties with click-to-explore functionality. React Leaflet provides declarative React components.

Features:

• GeoJSON county boundaries
• Click-to-view county details
• Broker coverage overlay
• Mobile-friendly touch interactions

Lucide Icons

Beautiful & consistent icon toolkit

lucide.dev | GitHub

Fork of Feather Icons with 1,400+ icons. We use lucide-react for React components and astro-icon with @iconify-json/lucide for Astro templates.

TanStack Query (React Query)

Powerful asynchronous state management

tanstack.com/query | GitHub

Server state management for our admin panel. Handles caching, background refetching, and optimistic updates for a snappy user experience.

const { data: brokers } = useQuery({
  queryKey: ['brokers'],
  queryFn: () => api.get('/brokers'),
});

oidc-client-ts

OpenID Connect (OIDC) client for browser-based JavaScript applications

GitHub

TypeScript implementation of OIDC client for our Keycloak integration. Handles token refresh, silent renew, and logout flows.

Sonner

An opinionated toast component for React

sonner.emilkowal.ski | GitHub

Beautiful toast notifications that just work. Used throughout the admin panel for success/error feedback.

Backend Stack

FastAPI

Modern, fast web framework for building APIs with Python

fastapi.tiangolo.com | GitHub

Our REST API is powered by FastAPI—the fastest Python framework with automatic OpenAPI documentation, Pydantic validation, and async support.

Why FastAPI:

• Type hints generate automatic API docs
• Async/await for high concurrency
• Pydantic models for request/response validation
• Dependency injection for clean architecture

@router.get("/counties/{fips}", response_model=CountyResponse)
async def get_county(fips: str, db: AsyncSession = Depends(get_db)):
    """Fetch county by FIPS code with broker coverage."""
    ...

SQLAlchemy 2.0

The Python SQL Toolkit and Object Relational Mapper

sqlalchemy.org | GitHub

SQLAlchemy 2.0’s async support powers our data layer. Type-annotated models, relationship loading, and the new select() syntax make database code readable and safe.

class County(Base):
    __tablename__ = "counties"

    fips: Mapped[str] = mapped_column(String(5), primary_key=True)
    name: Mapped[str] = mapped_column(String(100))
    state: Mapped["State"] = relationship(back_populates="counties")

Pydantic 2

Data validation using Python type annotations

docs.pydantic.dev | GitHub

Request/response validation, settings management, and data serialization. Pydantic v2’s Rust-based core makes validation lightning fast.

Alembic

Database migration tool for SQLAlchemy

alembic.sqlalchemy.org | GitHub

Schema migrations with version control. Every database change is tracked and reversible.

# Generate migration from model changes
alembic revision --autogenerate -m "Add broker_county table"

# Apply migrations
alembic upgrade head

Uvicorn

Lightning-fast ASGI server

uvicorn.org | GitHub

Production-grade ASGI server running our FastAPI application. Built on uvloop for maximum performance.

HTTPX

A next-generation HTTP client for Python

python-httpx.org | GitHub

Async HTTP client for calling external services—Keycloak admin API, Stripe, and Ollama embeddings.

APScheduler

Advanced Python Scheduler

apscheduler.readthedocs.io | GitHub

Background job scheduler for our worker container. Runs the 30-day delinquency check and other scheduled tasks.

Data & Search

SQLite

The most used database engine in the world

sqlite.org

Yes, SQLite in production! For our use case (read-heavy, single-server), SQLite outperforms PostgreSQL while simplifying deployment. The entire county database fits in a single file.

Why SQLite works for HURE:

• 3,222 counties is a small dataset
• Read-heavy workload (90%+ reads)
• Single server deployment
• Simpler backups (copy one file)
• WAL mode for concurrent reads

sqlite-vec

A vector search SQLite extension

GitHub

Vector similarity search without leaving SQLite! Powers our semantic search for natural language queries like “affordable coastal state with military bases.”

SELECT name, vec_distance_cosine(embedding, ?) as distance
FROM states
ORDER BY distance
LIMIT 10;

Ollama

Get up and running with large language models locally

ollama.com | GitHub

Runs the mxbai-embed-large model for generating text embeddings. Our self-hosted instance at ollama.supported.systems keeps embedding generation fast and private.

Embedding workflow:

1. State/county description text
2. → Ollama mxbai-embed-large
3. → 1024-dimensional vector
4. → sqlite-vec for similarity search

Identity & Payments

Keycloak

Open Source Identity and Access Management

keycloak.org | GitHub

Enterprise-grade identity provider handling authentication for all user types. OIDC tokens include custom claims (broker_id, agent_id) for role-based access.

Features we use:

• OIDC/OAuth 2.0 authentication
• Role-based access control (admin, broker, agent, lead)
• Custom user attributes for entity linking
• Social login ready (future)
• Self-service password reset

Roles:

Stripe

Financial infrastructure for the internet

stripe.com | Stripe Python

Payment processing for broker subscriptions. Webhook integration handles payment success/failure with 30-day grace period for failed payments.

Integration points:

• Checkout Sessions for subscription signup
• Webhooks for payment events
• Customer Portal for self-service billing

python-jose

JavaScript Object Signing and Encryption (JOSE) for Python

GitHub

JWT validation for Keycloak tokens. Verifies signatures and extracts claims for authorization.

Infrastructure

Docker

Develop, ship, and run applications in containers

docker.com | GitHub

Every component runs in containers for consistent deployment. Multi-stage builds keep images small.

services:
  landing:    # Astro + Caddy
  api:        # FastAPI
  worker:     # APScheduler
  keycloak:   # Identity
  keycloak-db: # PostgreSQL for Keycloak
  mailhog:    # Dev email testing

Caddy

Fast and extensible multi-platform HTTP/1-2-3 web server with automatic HTTPS

caddyserver.com | GitHub

Our web server and reverse proxy. Automatic HTTPS via Let’s Encrypt, HTTP/3 support, and the elegant Caddyfile configuration.

Used for:

• Static file serving (Astro build)
• Reverse proxy to FastAPI
• Automatic TLS certificates
• gzip/brotli compression

caddy-docker-proxy

Caddy as a reverse proxy for Docker

GitHub

Automatic Caddy configuration from Docker labels. Add a container, add labels, get HTTPS routing.

labels:
  caddy: hometownusarealestate.com
  caddy.reverse_proxy: "{{upstreams 80}}"

uv

An extremely fast Python package and project manager

docs.astral.sh/uv | GitHub

Rust-powered Python package manager that’s 10-100x faster than pip. Our Docker builds use the official uv images.

FROM ghcr.io/astral-sh/uv:0.5-python3.12-bookworm-slim AS base

PostgreSQL

The World’s Most Advanced Open Source Relational Database

postgresql.org | GitHub

Powers Keycloak’s data storage. While our application uses SQLite, Keycloak runs on PostgreSQL for session management and user storage.

MailHog

Web and API based SMTP testing

GitHub

Development email testing. Captures all outgoing emails for inspection without sending to real addresses.

Developer Tools

Ruff

An extremely fast Python linter and code formatter

docs.astral.sh/ruff | GitHub

Rust-powered linter that replaces Flake8, isort, and Black. Catches errors and formats code in milliseconds.

Node.js 22

JavaScript runtime built on Chrome’s V8 engine

nodejs.org | GitHub

Powers our Astro build process and development server.

TypeScript

JavaScript with syntax for types

typescriptlang.org | GitHub

Type safety for our React components and API client code.

Observability

@casoon/astro-webvitals

Web Vitals tracking for Astro

GitHub

Real user monitoring for Core Web Vitals (LCP, FID, CLS, TTFB). Helps us maintain performance standards.

astro-seo-meta & astro-seo-schema

SEO utilities for Astro

Structured data (JSON-LD) and meta tag generation for search engine optimization.

Discovery & Standards

@astrojs/discovery

Machine-readable site metadata

Generates:

• robots.txt with LLM bot handling
• sitemap.xml for search engines
• security.txt (RFC 9116)
• llms.txt for AI agent discovery
• humans.txt for team credits

Philosophy

Why These Choices?

SQLite over PostgreSQL: For our read-heavy workload with ~3,000 counties, SQLite is faster and simpler. No connection pooling, no separate database server, trivial backups.

Keycloak over Auth0/Clerk: Self-hosted identity means no per-user pricing, full data ownership, and enterprise features included.

FastAPI over Django: Async-first, type hints, automatic OpenAPI docs. Perfect for API-only backends.

Astro over Next.js: Static-first with partial hydration. For a content-heavy site, Astro’s “ship zero JS by default” philosophy is perfect.

Caddy over Nginx: Automatic HTTPS, human-readable config, HTTP/3 support. Modern web server for modern applications.

Thank You

To every maintainer, contributor, and community member behind these projects: thank you.

HURE exists because brilliant people chose to share their work with the world. We’re proud to build on this foundation and give back where we can.

Testing Results

• ✅ All services start successfully with docker compose up
• ✅ Caddy obtains TLS certificates automatically
• ✅ FastAPI health checks pass
• ✅ Keycloak authentication flow works
• ✅ SQLite + sqlite-vec vector search returns relevant results
• ✅ Stripe webhooks process correctly
• ✅ Email delivery works (MailHog in dev, SMTP in prod)