System Architecture

Current System State

Today zolotoy.dev is one Vue 3 SPA (the interactive demo) served as static assets, plus a statically generated portfolio layer describing the work. The demo runs fully on MSW-mocked APIs in mock mode; VITE_API_MODE=real switches transport targets to configured hosts without loading the mock graph.

The backend repository contains one implemented Go module: the order HTTP service at the Service Layer milestone. It validates requests, calls a service layer, and returns demonstration results. Domain state machines exist as separate packages and are not yet wired into the HTTP flow. PostgreSQL, Redis, Kafka, auth and live frontend integration are not connected.

Current Architecture

Browser → frontend typed transport (native fetch through module API facades) → MSW interception for the mock demo. TanStack Query owns server state; Pinia stores are deliberately narrow (session, runtime, theme).

In parallel, the Go order service runs locally: POST /orders and GET /orders/{id} validate input and delegate to a service layer. There is no live connection between the public demo and the Go service — the demo is mocked by design until the auth and contract work lands.

• Current

  Demo flows run on deterministic MSW scenarios; unhandled requests to configured service origins fail closed with 501 MOCK_UNHANDLED_REQUEST.

• Current

  The Go order service is a separate local implementation: HTTP validation → service call, no persistence, no tests yet.

• Current

  Order domain models and transition methods exist but are not integrated with the HTTP flow.

Target Architecture

The target is four independently owned services behind /api/v1 with explicit data ownership and an event contract between Order and Notification. All infrastructure in the target diagram — PostgreSQL, Redis, Kafka — is planned, not deployed.

• Target

  Auth owns users, credentials and sessions. Other services never read credential tables.

• Target

  Order owns orders, payment-related state, history and outbox records.

• Target

  Notification owns inbox records, delivery jobs and delivery attempts.

• Target

  Shortener owns links and bounded analytics.

• Target

  Services do not query each other’s private tables; shared deployment infrastructure does not imply shared business-data ownership.

• Target

  Order events feed Notification through a defined event contract via a transactional outbox.

Service Boundaries

Each service exposes its own /api/v1 namespace and owns its storage. The frontend treats them as independent modules behind one shared transport and error model. Cross-service claims (for example order-role vs auth-role mapping) are explicit integration contracts, not implicit database joins.

Data Ownership

Order: orders, lifecycle history, payment state transitions, outbox records. Auth: users, credentials, sessions and refresh families. Notification: inbox, delivery jobs, attempts. Shortener: links and bounded analytics. Nothing else reads these tables directly; integrations go through APIs or the event contract.

Mock vs Live Runtime

Mock mode is the default: MSW intercepts the same network path the real transport uses, with deterministic scenarios and reset. Real mode never loads the mock handler graph. The demoMode field in each case study (mock/mixed/live) is portfolio evidence about the visible demo flow — it does not claim backend deployment.

Architectural Principles

Boundaries over shortcuts: transport parsing never reaches business logic; services never reach into each other’s storage. Honesty over marketing: current ≠ target ≠ measured, and planned infrastructure is always labelled. Failure modes are designed, not discovered: idempotency, concurrency and at-least-once semantics are first-class content.

Roadmap Relationship

The architecture above is the destination of the milestone sequence: Order → persistence → lifecycle/concurrency → Auth → live frontend → events → Notification → Shortener → observability. Each case study’s Next Milestone section names the immediate step and its acceptance evidence.

Integration Contracts (unresolved areas)

These areas require explicit API-contract decisions before the corresponding frontend flows switch from mock to live. None of them has a canonical OpenAPI document yet.