System Architecture
High-level topology, service boundaries, and communication patterns.
System Architecture Overview
Wordloop is a localized, intelligence-first platform structured so that each service owns an isolated domain boundary, communicating through strictly typed, declarative contracts.
High-Level Topology
Service Boundaries
The platform is decoupled into three primary execution domains:
wordloop-core (Go)
The absolute system of record. Responsible for transactional orchestration, state management, Clerk webhook syncing, and exposing the primary REST API via Huma.
wordloop-ml (Python)
The async intelligence engine. Stateless, event-driven, and built on FastAPI. It consumes Pub/Sub events from Core, interfaces with external APIs (AssemblyAI), and uses a symmetric service token to push structured data back to Core.
wordloop-app (Next.js)
The presentation layer built on React Server Components. Authenticates via Clerk and communicates with Core via Orval-generated API clients wrapped in a Next.js server-side proxy route.
Communication Patterns
Contracts act as the sole source of truth. Hand-written API clients are forbidden.
| Pattern | Mechanism |
|---|---|
| Synchronous Data (UI) | HTTP REST via Orval-generated React clients. Next.js proxies to circumvent CORS arrays and build-time env constraints. |
| Real-Time Feed | WebSockets for reactive UI updates. |
| Worker Dispatch | GCP Pub/Sub utilizing strict AsyncAPI schemas. |
| Internal Writebacks | Internal REST calls authenticated via strict Service Tokens. |
| Identity Sync | Webhooks from Clerk ingested to local Postgres users table. |
See the dedicated documentation for Authentication, Observability, and Hosting.