​

DJMEXXICO (xico-city) Low-Level Architecture

Date: 2026-05-05 Updated: 2026-05-05 — product identity corrected to DJMEXXICO; code fixes applied. Status: Canonical for xico-city technical design and ecosystem integration map. Scope: Requirements completeness, system boundaries, runtime topology, data model, API contracts, and Factory ecosystem dependencies.

---

​

1. Executive Answer

​

Are core requirements, architecture, and design complete?

Not yet.

• Product requirements are detailed and locked in BUILD_PLAN_v2.md (DJMEXXICO canonical spec).
• Architecture intent exists across multiple docs, but there was no single low-level canonical spec in Factory.
• Runtime code partially reflects the correct architecture; gaps remain at auth layer and processor integration.

This document is the canonical low-level architecture reference.

​

Do we know what xico-city connects to in the greater ecosystem?

Yes. Connections are now explicit in this document and in docs/service-registry.yml. Canonical public domain: xicocity.com.

---

​

2. Canonical Product Intent

DJMEXXICO is a creative economy operating system for artists, NOT a Mexico City experiences marketplace. BUILD_PLAN_v2.md §1.2 is explicit: “This is not a Mexico City booking app. Any document describing it as one is wrong and must be corrected.” Product scope:

• 11 artist roles across music, visual art, and performance (Producer, Vocalist, DJ, VJ, Songwriter, Engineer, Visual Artist, Curator, A&R, Supervisor, Promoter)
• Artists upload raw material → platform processes → production-ready assets → marketplace
• Buyers discover and purchase via Stripe Checkout; sellers connect Stripe Connect
• Audio/image/video processing runs on Hetzner CX32 Python worker (librosa, Demucs, Pillow, ffmpeg) — not in the Worker
• Build-time LLM orchestration: OPUS→HAIKU loop (claude-opus-4-5 → claude-haiku-4-5)

Source-of-truth docs:

• Latimer-Woods-Tech/xico-city/BUILD_PLAN_v2.md — canonical product spec (wins on all conflicts)
• Latimer-Woods-Tech/xico-city/legacy/DJMEXXICO_BuildRequirements_v1.md — full business rules and ACs (“the build bible”)
• docs/service-registry.yml (Factory) — infrastructure registry

Prior Factory docs describing xico-city as a “Mexico City experiences marketplace” were incorrect and have been corrected.

---

​

3. Known Divergences (Fixed 2026-05-05)

---

​

4. Requirements Completion Matrix (DJMEXXICO Canonical)

---

​

5. Target Runtime Topology

​

5.1 API Worker (Cloudflare Workers + Hono v4)

1. Client surfaces (web PWA) call DJMEXXICO Worker API.
2. Worker enforces auth (Lucia sessions — target state), business rules, rate limits.
3. Worker reads/writes Neon Postgres via Hyperdrive DB binding.
4. Worker writes presigned R2 URLs for asset storage.
5. Worker executes Stripe Checkout, Connect, and webhook handling.
6. Worker enqueues processing jobs via Cloudflare Queues to Hetzner worker.

​

5.2 Hetzner CX32 Python Worker (External Compute)

• Audio: librosa, pydub, pyloudnorm, Demucs, Essentia, mutagen, ffmpeg
• Visual: Pillow, Replicate/FLUX/SDXL, ffmpeg
• Communicates with Cloudflare Worker via Cloudflare Queues and direct HTTP (PROCESSOR_URL)
• Cannot run inside a Cloudflare Worker — documented waiver in BUILD_PLAN_v2.md §2

​

5.3 LLM (Build-Time Only)

• OPUS→HAIKU orchestration loop (claude-opus-4-5 → claude-haiku-4-5 → OPUS review)
• Not a runtime dependency; not exposed to end users in v1

---

​

6. Low-Level Component Design

​

6.1 HTTP/API Layer

• Framework: Hono v4
• Global error handling via @latimer-woods-tech/errors
• Sentry middleware via @latimer-woods-tech/monitoring
• Auth: Lucia Auth v3 (Neon sessions, Argon2id) — per BUILD_PLAN_v2.md §2 auth row

Required base routes:

• GET /health → liveness (always 200 if Worker is running)
• GET /ready → readiness probes (DB + processor bindings; 200/503)
• GET /factory/compat → integration contract compat info
• GET /api/me → authenticated payload (temporary; will be replaced by Lucia session routes)

​

6.2 Data Layer (Target State — Requires Schema Migration)

Current schema reflects experiences/bookings tables (wrong product). Target DJMEXXICO schema per build bible:

• users, sessions (Lucia-compatible)
• artists, artist_roles
• assets, asset_versions, asset_tags
• jobs (processing queue jobs)
• listings, purchases
• stripe_events (idempotent Stripe ingestion)
• subscriptions
• factory_events (mandatory for Factory analytics ledger)

​

6.3 Security and Secrets

• No secrets in source or wrangler.jsonc vars.
• Worker secrets via wrangler secret put / GitHub Actions.
• Auth secret rotation per environment; Lucia session store in Neon.

​

6.4 Observability

• Sentry DSN required (Worker boots Sentry on first request).
• PostHog + factory_events both required.
• /health and /ready are mandatory deployment gates.

---

​

7. Ecosystem Integration Map

---

​

8. Verification Snapshot (2026-05-06)

• https://xico-city.adrper79.workers.dev/health → 200 ✅
• https://xico-city.adrper79.workers.dev/ready → 200 ✅ (route fix confirmed)
• https://xico-city-staging.adrper79.workers.dev/health → 200 ✅
• https://xico-city-staging.adrper79.workers.dev/ready → 200 ✅
• https://xicocity.com/health → 200 ✅ (custom domain live-verified 2026-05-06)

---

​

9. Remaining Open Work

1. Migrate auth from @latimer-woods-tech/auth JWT to Lucia Auth v3 — per BUILD_PLAN_v2.md §2. Current code is a temporary stub.
2. Migrate schema from experiences/bookings to DJMEXXICO asset/job model — current src/db/schema.ts is wrong for DJMEXXICO; requires new Drizzle schema + migration.
3. Redeploy staging — wrangler deploy --env staging after wrangler.jsonc fix to restore 200 at /health.
4. Verify xicocity.com custom domain — redeploy production with custom_domains in wrangler.jsonc; run curl https://xicocity.com/health for 200 confirmation; update registry status.
5. Wire Cloudflare Queues + DLQ — job dispatch to Hetzner processor is not yet configured.
6. Schema migration — replace experiences-era tables with DJMEXXICO canonical schema.

---

This file is the canonical low-level architecture and integration map for the DJMEXXICO worker (xico-city) inside Factory until superseded by a newer architecture version. This file is the canonical low-level architecture and integration map for the DJMEXXICO worker (xico-city) inside Factory until superseded by a newer architecture version.