Hoxa Architecture Overview

April 19, 202611 min read

I want the architecture to reflect the product posture: measured, modular, and explainable. It should be capable enough to support future intelligence and integrations, but simple enough that the training logic remains inspectable while the product is still taking shape.

System design should make the product easier to reason about, not more impressive to describe.

Start With The Product Loop

The architecture only makes sense if it mirrors the product loop. Hoxa begins with onboarding, moves into goal and profile setup, generates a weekly plan, captures workout completion, and then updates future plans based on recent behaviour. That sequence creates the minimum structure the rest of the system needs to support.

User
  |
  v
Onboarding
  |
  v
Goal Profile
  |
  v
Training Engine
  |
  v
Weekly Plan
  |
  v
Workout Completion
  |
  v
Progress + Adaptation

Core product flow

Representing the loop this way is helpful because it keeps the boundaries visible. The training engine is not the whole product. It is one layer in a broader system that also has to manage identity, schedule context, completion events, progress views, and eventually integrations.

Service Boundaries

For an early version, I would keep the architecture centred on a clean API layer and a small set of explicit domain services. The iOS app is likely the primary user-facing product surface. A web app can support companion experiences later, and an internal web surface can support operational tooling, content adjustments, and model inspection where useful.

iOS App -----------+
                    |
Web App -----------+---- API Layer ---- Training Engine
                    |             |
Admin Surface -----+             +---- Progress Service
                                  |
                                  +---- Social Service
                                  |
                                  +---- Integrations Layer

Primary component map

This structure is intentionally plain. The API layer should coordinate state transitions and keep the surface contracts stable. The training engine should focus on plan generation and adaptation. Progress should own completed sessions, streak-like continuity signals, and reporting views. Social should stay narrow and support accountability rather than becoming its own product.

Data Flow And Integrations

Future integrations matter, but they should enter the system through a controlled boundary. Apple Health, Apple Watch, Garmin, and calendar sources will all carry different levels of reliability, granularity, and latency. The system should normalize those signals before they touch training logic directly.

Apple Health ----+
Apple Watch -----+ 
Garmin ----------+---- Integrations Layer ---- Normalized Activity Events
Calendar --------+                              |
                                                 v
                                        Progress Service
                                                 |
                                                 v
                                          Training Engine
                                                 |
                                                 v
                                               Weekly Plan

Integration and adaptation flow

That separation matters for safety and reasoning. The training engine should consume a stable representation of recent activity and context, not a patchwork of vendor-specific event formats. It should also be possible to inspect what the system believed happened before explaining why the plan changed.

What This Enables Later

Once the boundaries are clean, later additions become more credible. Analytics can live alongside the progress layer without contaminating core plan logic. Generative AI can help translate plans, summarize trends, or explain changes without becoming the source of record. ML systems can support prediction and pattern detection, but they can remain advisory unless their role is well-validated.

Keep training rules and adaptation decisions inspectable in the early product.
Treat AI-generated language as presentation support, not authoritative programming logic.
Use service boundaries to make future integrations additive rather than destabilising.
Prefer a smaller number of clear domain services over a large mesh of premature microservices.

That is the main architectural goal for now: make it easy to evolve Hoxa without losing sight of how the product actually works. If the architecture obscures the training logic, it will be moving in the wrong direction.