Architecture Overview

System diagram

flowchart TB
    subgraph User
        U[Internal team / client]
    end

    subgraph Frontend
        FE[Alyson UI<br/>Next/CRA · Vercel<br/>app.alyson.ai]
    end

    subgraph Backend
        BE[Express JS API<br/>EC2 · pm2]
    end

    subgraph Experiment Manager
        EM[Temporal workflows<br/>EC2 → AWS EKS later]
        EB[EventBridge schedules]
    end

    subgraph Data
        PG[(RDS Postgres<br/>operational data)]
        AUR[(RDS Aurora<br/>IP lookup)]
        ATH[(AWS Athena<br/>analytics: TUNE, Segment, HomeLight)]
    end

    subgraph DS
        RPC[RPC model]
        CVR[CVR model]
    end

    U -->|browser| FE
    FE -->|REST| BE
    BE --> PG
    BE -->|create schedules| EB
    EB -->|fire| EM
    EM --> PG
    EM --> RPC
    EM --> CVR
    BE --> AUR
    BE -.->|reads aggregates from| ATH

Services in scope

Service	Repo	Stack	Hosting
Frontend	alyson-frontend	Create React App	Vercel (app.alyson.ai)
Backend	alyson-backend	Express JS	EC2 + pm2
Experiment Manager	alyson-experiment-manager	Temporal	EC2 (→ EKS)
DS Models	alyson-ds-models	Python	TBD
Data pipelines	various	Lambda / Glue	AWS

Per-service details live in /docs/20-services/.

Data stores

• RDS Postgres — primary operational store for the product. Multiple schemas (one for the Alyson product, others for non-product systems like the Pre-pop API; see ADR-0003 for context).
• RDS Aurora Postgres — small, just the IP-address lookup table.
• AWS Athena — analytics warehouse. Layered as raw.*, optimized.*, unified.*. See /docs/30-data/ for table-level docs.

Request flow: creating an experiment

1. User submits experiment-creation form in the Frontend.
2. Frontend calls the Backend API.
3. Backend writes experiment entities to Postgres and creates an EventBridge schedule.
4. At the scheduled time, EventBridge fires and invokes a Temporal workflow on the Experiment Manager.
5. The workflow grades agents periodically (using RPC / CVR model predictions) and updates split weights for auto-optimized experiments.

Click flow: live traffic

1. Affiliate sends a TUNE tracking link with prepop URL params.
2. User clicks. TUNE records the click and rotates the redirect to a landing page (split managed in TUNE today; will move into Alyson routers).
3. Landing page reads URL params (utm_content etc.) and fires Segment events.
4. If user submits the quiz, lead is sent to the buyer (HomeLight or other) with utm_content preserved.
5. Buyer reports lead/revenue back; we join everything by utm_content in Athena.

Where things will move

• Experiment Manager: EC2 → EKS.
• Backend: today is a monolith with non-Alyson APIs co-resident (e.g. Pre-pop). Plan is to extract those, but no work in flight yet.

Related

• Glossary
• Per-service docs under /docs/20-services/
• ADR-0001 — Docs as code