excel.aws.monce.ai  /  architecture

Architecture

Charles Dana · Monce SAS · May 2026

Two boxes. One bearer token. The rest is rendering.

1. The split

Two AWS-hosted surfaces. Each does one thing — but the add-in box now also runs a small dispatcher, so it is no longer "compute = none."

The Excel add-in calls same-origin /v6/* on this box. The dispatcher (under app/routes/snake.py) inspects the payload and decides: under 500 rows the call runs in-process here (no Lambda fee, ~30 ms–3 s wall-clock); at or above 500 rows it forwards to snakebatch.aws.monce.ai/v5/train with test_items inline (the only path the SDK currently supports end-to-end — see §9). The threshold is one env var: CLOUD_THRESHOLD.

2. Request flow — one cell, end to end

║  User types =PREDICT(A1:E120, "Délai", G1:K30) in cell L1
║
║  Office.js runtime calls our registered custom function
║       functions.js hosted at excel.aws.monce.ai/functions.js
║
║  function awaits Office.onReady, reads workbook setting
║       monceai_api_key  →  sk-monceai-...
║
║  POST https://excel.aws.monce.ai/v6/train           # same-origin, no CORS preflight
║       Authorization: Bearer sk-monceai-...
║       body: { data: [...], config: {target_index, n_layers}, test_items: [...] }
║
║  dispatcher (this box) reads len(data):
║       # <500 rows  →  in-process algorithmeai.Snake
║       # ≥500 rows  →  POST snakebatch.aws.monce.ai/v5/train (test_items inline)
║                                |
║                                v   (cloud path only)
║  snakebatch's api Lambda (eu-west-3) authenticates, fans out:
║       v6-worker(n=2000) splits binary → 2 children → ... → leaves call Snake()
║
║  predictions returned + telemetry:
║       { predictions: [...], _mode: "local"|"cloud", _elapsed_ms: 1623 }
║
║  custom function returns matrix; Excel spills L1:L30
║
║  taskpane "Last call" tile shows mode + ms

3. excel.aws.monce.ai — the box itself

4. Routes served

5. Where the auth + billing Lambdas will live

v0.5 ships these in the snakebatch Terraform module — not here — because they touch snake-batch-* resources (DynamoDB tables, S3 buckets, IAM scopes) that already live there. This EC2 only reads balances and renders UIs.

6. Security model in one diagram

                              api_key
                                 |
                                 |  bearer
                                 v
         │− HTTPS −│
         |                                                 |
   excel.aws                                          snakebatch.aws
   (chrome)                                            (compute)
         |                                                 |
         |  GET only                                       |  POST /v6/*
         |  (no DB writes)                                 |  with bearer
         v                                                 v
   DDB read                                          DDB read+write
   snake-batch-usage                                snake-batch-{users,usage}
        (dashboard)                                      (auth, billing)
                                                           |
                                                           v
                                                  S3 per-user prefix
                                              jobs/<sha256(email)>/...
                                                  IAM-scoped per key

The EC2 has no write access to user records or model storage — on purpose. If this box is ever compromised the blast radius is "dashboard reads stop"; balance and models stay safe behind the Lambda IAM boundary.

7. S3 model permanency

Every trained model lands in S3 under s3://snake-batch-monce/jobs/<sha256(email)>/<model_id>/model_stripped.json the moment training finishes. The retention policy is indefinite by default. We do not garbage-collect.

8. The monceai SDK and the v6/batch story

The published pip install monceai SDK exposes Snake.get_batch_prediction(items) which posts to snakebatch.aws.monce.ai/v6/batch/<model_id>. As of May 2026 that endpoint is not yet shipped — it 404s. The only working cloud predict path is /v5/train with test_items inline, which re-trains every call (correct results, suboptimal cost).

This box's dispatcher works around it with a thin CloudSnake shim (app/routes/snake.py) that calls /v5/train directly. When /v6/batch ships, that shim is deleted and replaced with a one-line from monceai import Snake. Until then, cloud-mode predictions cost an extra training pass per call — baked into the economics table as the cloud row.

9. What we deliberately did not build

• No CodeDeploy / blue-green. One box, one rsync, 30s deploy. Reversible by re-rsync.
• No Docker. Python venv on the OS. Smaller cognitive surface for a tiny service.
• No Redis / queue. snakebatch's Lambda fan-out is the queue.
• No CDN in front of static assets. nginx serves /manifest.xml and friends; AppSource will fetch it on listing approval, not at runtime, so cache hit rate is meaningless.
• No SSO / OIDC for Excel auth. Magic-link via SES is enough for v0.6; Microsoft OAuth is a v2 add-on for enterprise tenants.
• No multi-tenant DB in v0.2. The dispatcher gates on a single MONCEAI_PERSONAL_KEY env var (sha256-compared) instead of a users table. v0.6 swaps this for the snakebatch DDB-backed flow without touching the client.