Overview

What is Alyson AI?

Alyson AI is our internal experimentation and orchestration platform for marketing campaigns. It unifies things that used to live in many separate tools — affiliate management (TUNE), landing-page splits, email and SMS campaign delivery, audience management, lead routing — into one product.

The first client of Alyson is our own internal Revenue / Marketing / Lead Gen team. Later it will be productized as SaaS for similar lead-gen companies.

Core concepts

If you only learn three things, learn these:

1. Experiments are the unit of work. An experiment compares multiple agents against each other and against a client champion, and grades them on chosen objectives (revenue, conversion) using predictions.
2. Agents are a wrapper around a router + an orchestrator. The router decides where traffic goes (which landing page, which messaging task), the orchestrator runs any downstream work.
3. Routers come in three flavors: manual split (weighted load balancing), model-based (ML picks per click), and segment-based (rule-based per audience attribute).

See the glossary for the full vocabulary.

How this documentation is organized

The folders are numbered so navigation is predictable in both filesystem and sidebar.

• 00-start-here/ — what you're reading. Onboarding, glossary, big-picture architecture.
• 10-product/ — the what and why of features. Concepts, requirements, user flows.
• 20-services/ — the how. Per-service technical docs: backend, frontend, experiment manager, DS models, data pipelines.
• 30-data/ — schemas, datasets, lineage. Both the operational Postgres data and the analytical Athena data.
• 40-operations/ — runbooks, monitoring, alerting.
• 50-adrs/ — architectural decision records.
• 90-sops/ — how we work. Development conventions and the meta-docs for how to maintain this documentation.

Who this is for

Primarily engineers and AI coding agents (Claude Code, Cursor, Codex, Copilot). It's deliberately written so a human can read it linearly and an agent can grep / retrieve from it. Non-engineers (PMs, ops, support) are also welcome — use AI to summarize anything that feels too technical.

Conventions

• Every doc has YAML frontmatter with title, owner, source_repos, last_verified, and status. This drives the staleness checker and the dashboard.
• Code blocks include the language tag ( ```bash, ```ts, etc.).
• Cross-links use the URL form (/docs/...), not relative file paths.
• ADRs are numbered sequentially and never renumbered, even when superseded.

Contributing

See Documenting Features for the workflow. See Using AI for Docs for the agent workflow specifically.