Architecture
What runs in your account, what each part does, and how the parts talk.
eode runs as two always-on workloads, one engine per active user, and four AWS services.
How your data moves
- Your data arrives. A user uploads an Excel or CSV workbook in the web app, or a data connection syncs rows from
your source. Either way,
eode-appreads and checks it. - It's stored. The rows, and the original file, are kept in PostgreSQL as a dataset. Every later step reads from there.
- It's solved. When a user builds or runs a model,
eode-apploads the data into that user's engine, which solves it. The data reaches the engine fromeode-app. - Results are stored.
eode-appwrites the results to PostgreSQL, one scenario at a time. - You read the results in the web app, or through an MCP client, both served by your install.
RIA works across these steps in a conversation. To answer, it sends your LLM provider what it needs: your question, the text of any document you attach, a profile and a few sample rows of each sheet, and the data and results it reads while working. See Network and security.
What runs where
The lines show the main paths. eode-mcp also uses the database and cache, eode-migrate reaches only the database,
and every workload reads its keys from Secrets Manager. Outbound calls to your LLM provider and the sign-in service
come from eode-app and eode-mcp; your nodes pull images from the registry.
Workloads
All of them come from two images, eode-app and eode-engine.
| Workload | Namespace | Port | Health | What it does |
|---|---|---|---|---|
eode-app | eode | 8787 | GET /api/health | The web app and its API. Signs users in, runs RIA's conversations, starts and stops engines |
eode-mcp | eode | 8848 | GET /healthz, MCP at /mcp | The MCP endpoint. Checks the caller's token, then works on that user's engine |
| Engines | eode-engines | 50051 | — | One per active user, created on demand, removed after 30 idle minutes |
eode-migrate | eode | — | exits 0 | Applies database changes before each install and upgrade. The only workload that can read the database owner login |
eode-app and eode-mcp can create and delete Deployments, Services and Jobs in eode-engines, and nowhere else. Engines run only on
the engine node group, sized by the model they hold (12, 24 or 48 GiB of memory by default; set by EngineMemoryClasses), and need about half a CPU
each. Every engine has its own working folder on the shared EFS file system, and reads the starter model library from it;
eode-app and eode-mcp see it read-only.
Where your data lives
Everything below is in your AWS account. Your users reach eode through the web app or an MCP client; both work on the same data.
| Store | Holds |
|---|---|
| RDS PostgreSQL | Users and organizations, datasets (the rows and the original files), model and scenario records, solve results, conversations |
| EFS | The starter model library, and each user's engine working folder |
The eode-app image | The reference knowledge RIA reads about modeling and optimization. It's read-only and changes with each release |
| ElastiCache Redis | Coordination between the web app's copies: which copy is running which conversation, and which engine is busy. Nothing here is the only copy |
| Secrets Manager | Keys and logins (see Secrets) |
Two services outside your account see your data: your LLM provider receives what each conversation with RIA sends it, and the sign-in service receives your users' sign-in details. Every outbound connection is on Network and security.
What the stack creates
| Nested stack | Creates |
|---|---|
| Network | A VPC across 2 or 3 availability zones with public and private subnets and NAT, or nothing (existing VPC). No DNS records |
| Cluster | A new Amazon EKS cluster with a general node group and a tainted engine node group, Pod Identity, and the EFS CSI add-on |
| Data | RDS PostgreSQL 16 (private, encrypted, automated backups), ElastiCache Redis (TLS + AUTH), EFS with an access point and automatic backups, and their security groups |
| Secrets | The eode/* secrets in Secrets Manager, generated where nobody needs to know them, and the IAM roles each workload uses |
| Installer | A CodeBuild project that installs the gateway, cert-manager and the secrets driver, prepares the database, installs eode, and checks that the web app answers |