docs(specs): multi-account execution draft spec

[cristim]

Summary

Adds specs/multi-account-execution/ — design doc set covering CUDly's planned move from one-account-per-provider to N-accounts-per-provider across AWS / Azure / GCP. Status: Draft (created 2026-04-02).

Nine documents, doc-only, no code changes:

File	Contents
README.md	Problem statement, scope, document index
acceptance.md	Gherkin-style acceptance criteria
api.md	REST surface changes (account CRUD, overrides)
backend.md	Handler + scheduler + collection-pipeline impacts
data-model.md	New DB tables, column additions, migration plan
frontend.md	UI flows (account list, per-account dashboards)
iac.md	Terraform module changes for multi-account federation
security.md	Credential storage, audit log, scoped tokens
tasks.md	Phased implementation plan, one atomic commit per task

Why this PR is just docs

No implementation has shipped yet — the live scheduler still collects per-provider, not per-account-per-provider. Recent shipped work (32f9e4ffc history pending, b44283746 failed/expired states, b3fe6e225 Azure scheduler dedupe) was scoped to keep the existing single-account model working; this spec is the substrate the next implementation phase will land against.

Landing the spec early means subsequent feature PRs can reference it without re-deriving the design every time.

Markdownlint note

The repo's markdownlint config defaults to "consistent" table-column style and "language-required" fenced code blocks. The spec was authored before the rules tightened; rather than reflow ~20 tables and tag every fenced block, each file opens with a <!-- markdownlint-disable MD040 MD060 --> directive scoped to that file. When the spec stops being draft and graduates to canonical docs, those can come off and the tables/code blocks can be normalised in the same pass.

Test plan

• No hardcoded secrets: grep for AKIA|client_secret|private_key|password returned only schema field names and example placeholders (AKIA...).
• Pre-commit hooks pass (markdownlint clean with the per-file disable).
• Word/line counts match expectation: 3,030 lines, ~111 KB across 9 files.

[coderabbitai]

Warning

Rate limit exceeded

@cristim has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 3 minutes and 17 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7222405a-965d-44b8-9188-70cae2c8f1c4

📥 Commits

Reviewing files that changed from the base of the PR and between a86bd4d and 190e609.

📒 Files selected for processing (9)

• specs/multi-account-execution/README.md
• specs/multi-account-execution/acceptance.md
• specs/multi-account-execution/api.md
• specs/multi-account-execution/backend.md
• specs/multi-account-execution/data-model.md
• specs/multi-account-execution/frontend.md
• specs/multi-account-execution/iac.md
• specs/multi-account-execution/security.md
• specs/multi-account-execution/tasks.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/multi-account-execution-spec

---

_{Review rate limit: 0/5 reviews remaining, refill in 3 minutes and 17 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cristim]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

Rebased onto current feat/multicloud-web-frontend to bring CR review current. @coderabbitai review

[coderabbitai]

@cristim Sure! Triggering a review of the rebased changes now.

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

Closing without merge. The spec was authored 2026-04-02; ~85% of it has shipped incrementally since and the PR description never got updated, so merging the docs as-written would mislead future readers about the implementation state.

What shipped (verified with file:line citations)

• Cloud-accounts CRUD + storage — internal/database/postgres/migrations/000011_cloud_accounts.up.sql:1-142, internal/api/handler_accounts.go:165-410
• Encrypted credential storage (AES-256-GCM) — internal/credentials/cipher.go, internal/config/store_postgres.go:1701-1730
• AWS auth modes (access_keys, role_arn, bastion, workload_identity_federation) — internal/credentials/resolver.go:90-180+
• Multi-account scheduler with errgroup parallel fan-out + per-account error isolation + cloud_account_id tagging — internal/scheduler/scheduler.go:370-430,562-574,601-607
• cloud_account_id columns on purchase_history, purchase_executions, savings_snapshots, ri_exchange_history (nullable, backward-compatible) — migrations/000011:125-142
• Account filtering on Recommendations / Dashboard / History — frontend/src/{recommendations,dashboard,history}.ts
• account_service_overrides cascade with sparse override resolution — migrations/000011:78-107, internal/config/resolver.go:ResolveServiceConfig, settings UI in frontend/src/settings.ts:591-800+
• plan_accounts join table + SetPlanAccounts/GetPlanAccounts endpoints — migrations/000011:113-119, internal/config/store_postgres.go:1890-1960+

What still needs to ship → individual issues

Issue	What
#208	feat(accounts): wire the AWS Organizations discovery endpoint to the already-implemented DiscoverOrgAccounts (currently a stub). p1, severity/high, effort/m.
#209	feat(api): validate plan account provider matches the plan's provider on assignment (acceptance E-4). p1, severity/high, effort/s.
#210	test(purchase): regression guard for parallel multi-account execution isolation (acceptance E-2). p1, severity/high, effort/m.
#211	docs(schema): document recommendations cloud_account_id filter semantics + add tests (acceptance D-1/D-3/D-4). p2, severity/medium, effort/s.

Why close vs. refresh-in-place

Considered refreshing this PR's description and merging the spec docs. Decided against because:

1. The Status: Draft headers and the "no implementation has shipped yet" framing in the README would still mislead future readers — the docs are not actually a draft anymore for the parts that shipped.
2. Each shipped piece already has its own implementation PR with the design rationale captured in the commit message + tests; another canonical docs site competes with that.
3. The 4 follow-up issues capture the residual work with file:line specificity that lets each be picked up independently. The spec's document-level structure was useful for the design phase; for the gap phase, ticket-per-thing is sharper.

The 9 design docs in this branch are still individually useful — happy to extract any of them into docs/design/ as a separate PR if a specific reader wants the canonical reference. Otherwise the branch will get garbage-collected after close.