Repository navigation
docs: architecture map with a numbered diagram - #1
Conversation
Add docs/architecture.md: the components, the trust and data boundaries, the path one request or run takes through the system as numbered steps that match the arrows on docs/architecture.svg, and a table of what is proven and where the evidence lives. The README gains an Architecture section that shows the diagram and links the page. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Expand the canvas and nested regions, widen boxes, and separate actor and AWS service columns so all text has room. Reroute connections orthogonally, align queue ports, and place labels and numbered badges clear of neighboring objects and borders. Wrap two edge labels and two notes without cutting any words or facts. Preserve every component, edge, numbered step, and style; architecture.md and README remain unchanged. Verified in three render-and-inspect rounds, with a passing geometry gate and no edge intersections. Co-Authored-By: Codex astra <noreply@openai.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 86fffe1cce
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 6. **Reviewer → the service.** The React console, served by the jar at `/console/`, lists `GET /approvals?status=PENDING`, shows `GET /approvals/{id}/transfer`, and posts `POST /approvals/{id}/approve` or `/deny` with `decidedBy` and `reason`. This is HTTP, not SQS. `ApprovalService` hands the result to `TransferSettlementService`: approve consumes the reservation and posts the entries; deny releases it and the transfer becomes `REVERSED`. `ApprovalExpiryWorker` does the same for approvals that pass their TTL. Every step appends to `audit_records`. | ||
| 7. **Operator → the service.** `POST /admin/reconciliation?date=` runs a reconciliation on demand; `POST /admin/dlq/replay` moves dead-lettered messages back, with an audit record. The replay endpoint exists only when `teller.aws.enabled=true`. | ||
| 8. **Service ↔ Amazon S3.** `ReconciliationScheduler` (cron `0 5 0 * * *` UTC) writes `entries/dt=YYYY-MM-DD/run-<uuid>.jsonl` and `audit/dt=…/run-<uuid>.jsonl` to the versioned `teller-audit` bucket, reads the entries back, and compares identities, counts, per-currency totals and cached balances. The result lands in `reconciliation_runs`; a mismatch appends `RECONCILIATION_MISMATCH` and raises `teller.reconciliation.mismatch`. | ||
| 9. **Service → Amazon CloudWatch.** Logs go to `teller-application` (kept one week). The `Teller` dashboard shows `teller.transfers.terminal`, `teller.reservations.active`, `teller.outbox.sent` and `teller.outbox.failed`. The `teller-http-5xx` alarm derives from the request logs. |
There was a problem hiding this comment.
In the deployed AWS configuration, infra/lib/service-stack.ts:143-163 builds the Teller dashboard with HTTP 5xx, DLQ depth, ECS CPU/memory, and RDS CPU/connections only; it does not add any of these four application meters, and the application has no CloudWatch meter-registry dependency that would publish them automatically. Operators following this architecture page therefore will not find the claimed transfer, reservation, or outbox metrics in CloudWatch, so either wire those meters into CloudWatch/dashboard widgets or document the metrics that are actually present.
Useful? React with 👍 / 👎.
| | Throughput and latency at 0.5 vCPU | [`evidence/perf.md`](./evidence/perf.md) | | ||
| | The AWS deployment answers end to end; the deploy pipeline ran | [`evidence/aws-smoke.md`](./evidence/aws-smoke.md), [`evidence/pipeline.md`](./evidence/pipeline.md) | | ||
|
|
||
| The README reports the simulation campaign's totals (seeds, steps and transfers). The coverage file behind them is generated into `target/`, which is not committed, so rerun `SimulationTest` to regenerate it. |
There was a problem hiding this comment.
Running SimulationTest as instructed does write this file, but SimulationTest.DEFAULT_SEEDS is 200, while the README totals that this paragraph says to regenerate came from 2,000 seeds. A normal rerun will overwrite target/sim-coverage.json with a materially different campaign and cannot reproduce the cited steps and transfer totals; the instruction should explicitly pass -Dsim.seeds=2000 (and ideally give the complete command).
Useful? React with 👍 / 👎.
docs: architecture map with a numbered diagram
1 participant
Adds a reference-architecture drawing and a walkthrough for this repository.
docs/architecture.svg: boxed regions, component icons and numbered arrows, rendered from a JSON spec and checked by a geometry gate (text fits its box with slack for wider fonts; nothing touches or crosses anything else).docs/architecture.md: the numbered path arrow by arrow, the component table, the trust and data boundaries, what is proven and where the evidence lives, and the identifiers the code relies on. Every claim comes from this repository's own README, ADRs and code, and the page says what is not claimed.Two commits: the map, then the geometry pass.