WordloopSystem 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
The client–server data architecture follows the Optimistic Mutation with Echo-Suppressed Streaming pattern: REST for writes, WebSocket for reads, with optimistic UI and source-aware echo suppression for multi-device sync. Contracts act as the sole source of truth. Hand-written API clients are forbidden.
| Pattern | Mechanism |
|---|---|
| Mutations (CUD) | REST via Orval-generated clients. Optimistic UI with rollback. Next.js proxies to circumvent CORS. |
| Streaming Reads | WebSocket pushes complete entity payloads on every state change. Echo suppressed via X-Client-Id. |
| Worker Dispatch | GCP Pub/Sub utilizing strict AsyncAPI schemas for inter-service async work. |
| Internal Writebacks | Internal REST calls authenticated via strict Service Tokens (ML → Core). |
| Identity Sync | Webhooks from Clerk ingested to local Postgres users table. |
See the dedicated documentation for Authentication, Data Flow, Observability, and Hosting.