| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 6 | 3 | 0% |
| Commands | 0 | 0 | 2 | 0% |
| Section tags | 3 | 3 | 1 | 43% |
What each file covers
Sections
0 shared · 6 only in A · 3 only in B- − Acheron — AI agent & contributor guide
- − What this is
- − Layering (keep these boundaries)
- − Store roles (do not blur)
- − Conventions in brief (see the scoped rules for detail)
- − Docs are a first-class deliverable
- + Testing Conventions
- + Unit vs integration
- + What to cover
Commands
0 shared · 0 only in A · 2 only in B- + pytest
- + pytest -m integration
Section tags
3 shared · 3 only in A · 1 only in B- − do-not
- − agent-behaviour
- − docs
- + testing-strategy
- test
- lint-format
- code-style
Line diff
jleist-clemson/acheron · AGENTS.md
@@ −1 @@
1# Acheron — AI agent & contributor guide
2
3Vendor-neutral project context, shared across AI coding tools. Cursor reads this
4file natively; Claude Code reads it via the `@AGENTS.md` import in `CLAUDE.md`.
5Tool-specific rules live in `.cursor/rules/` (Cursor, glob-scoped via `globs:`)
6and `.claude/rules/` (Claude Code, imported from `CLAUDE.md` so they load every
7session) — keep those mirrors in sync with each other and with this file.
8`ARCHITECTURE.md` is the authoritative design document.
9
10## What this is
11
12`acheron` is a Distributed Event Processing Platform. Write path:
13`POST /events` → bounded in-process `asyncio.Queue` → async worker →
14**MongoDB (source of truth)**. Elasticsearch is a **derived mirror**, populated
15strictly downstream from a Mongo outbox (`es_indexed` marker) by the `EsIndexer`.
16Redis caches the realtime stats summary.
17
18## Layering (keep these boundaries)
19
20- `app/api/` — HTTP only: translate request ↔ domain, map errors to status codes.
21- `app/ingestion/`, `app/worker/` — pipeline logic (enqueue, consume, index, rollup).
22- `app/storage/`, `app/cache/`, `app/queue/` — one backend per module.
23
24Business logic lives in services/stores, never in route handlers.
25
26## Store roles (do not blur)
27
28- **Mongo is authoritative.** If Mongo and ES disagree, Mongo wins.
29- **ES is best-effort and rebuildable** — never fail an authoritative write on it.
30- **Redis is a cache** — a Redis outage must degrade, never lose data.
31- The queue is **in-process and non-durable**; that constraint drives most
32 failure-mode and scaling reasoning. Don't design as if it were durable.
33
34## Conventions in brief (see the scoped rules for detail)
35
36- `from __future__ import annotations` atop every module; Google-style docstrings
37 (ruff `D`, pydocstyle google). Tunables live in `Settings`, not magic numbers.
38- Routes are thin; the events routes declare a Pydantic `response_model`
39 (`/health` and `/metrics` are intentionally exempt). Errors map to status
40 codes (Mongo→503, ES→502, queue full→429, shutdown→503).
41- Tests: pytest with `asyncio_mode=auto`; unit tests are hermetic, Docker-backed
42 tests are marked `integration` and deselected by default.
43
44## Docs are a first-class deliverable
45
46When you change behavior, update `ARCHITECTURE.md` and `README.md` in the same
47change. Code and docs must not drift — the architecture doc is graded.
48
jleist-clemson/acheron · .cursor/rules/testing.mdc
@@ +1 @@
1---
2description: Testing conventions (pytest, asyncio, unit vs integration)
3globs: tests/**/*.py
4alwaysApply: false
5---
6
7# Testing Conventions
8
9- `pytest` with `asyncio_mode = auto` — write `async def test_*` directly, no
10 per-test `@pytest.mark.asyncio` needed.
11- Test functions take **no docstrings** (the name is the description; ruff `D`
12 rules are disabled under `tests/`). Use a clear `test_<behavior>` name instead.
13- Build event payloads via `tests/factories.py`, not inline dicts, so the event
14 shape stays in one place.
15
16# Unit vs integration
17
18- **Unit tests** must be hermetic: mock stores/clients, require no Docker, and
19 run under the default `pytest` invocation.
20- **Integration tests** that need real services (testcontainers / Docker) must be
21 marked `@pytest.mark.integration` (or live in a module marked `pytestmark =
22 pytest.mark.integration`). They are deselected by default; run with
23 `pytest -m integration`.
24
25# What to cover
26
27Prioritize business logic and error/degradation paths: retry→backoff→DLQ,
28backpressure (`QueueFull` → 429), cache miss→hit, and graceful degradation when
29ES/Redis are down. Don't test framework behavior.
30
@@ −1 +1 @@
1−# Acheron — AI agent & contributor guide
1+---
2+description: Testing conventions (pytest, asyncio, unit vs integration)
3+globs: tests/**/*.py
4+alwaysApply: false
5+---
26
3−Vendor-neutral project context, shared across AI coding tools. Cursor reads this
4−file natively; Claude Code reads it via the `@AGENTS.md` import in `CLAUDE.md`.
5−Tool-specific rules live in `.cursor/rules/` (Cursor, glob-scoped via `globs:`)
6−and `.claude/rules/` (Claude Code, imported from `CLAUDE.md` so they load every
7−session) — keep those mirrors in sync with each other and with this file.
8−`ARCHITECTURE.md` is the authoritative design document.
7+# Testing Conventions
98
10−## What this is
9+- `pytest` with `asyncio_mode = auto` — write `async def test_*` directly, no
10+ per-test `@pytest.mark.asyncio` needed.
11+- Test functions take **no docstrings** (the name is the description; ruff `D`
12+ rules are disabled under `tests/`). Use a clear `test_<behavior>` name instead.
13+- Build event payloads via `tests/factories.py`, not inline dicts, so the event
14+ shape stays in one place.
1115
12−`acheron` is a Distributed Event Processing Platform. Write path:
13−`POST /events` → bounded in-process `asyncio.Queue` → async worker →
14−**MongoDB (source of truth)**. Elasticsearch is a **derived mirror**, populated
15−strictly downstream from a Mongo outbox (`es_indexed` marker) by the `EsIndexer`.
16−Redis caches the realtime stats summary.
16+# Unit vs integration
1717
18−## Layering (keep these boundaries)
18+- **Unit tests** must be hermetic: mock stores/clients, require no Docker, and
19+ run under the default `pytest` invocation.
20+- **Integration tests** that need real services (testcontainers / Docker) must be
21+ marked `@pytest.mark.integration` (or live in a module marked `pytestmark =
22+ pytest.mark.integration`). They are deselected by default; run with
23+ `pytest -m integration`.
1924
20−- `app/api/` — HTTP only: translate request ↔ domain, map errors to status codes.
21−- `app/ingestion/`, `app/worker/` — pipeline logic (enqueue, consume, index, rollup).
22−- `app/storage/`, `app/cache/`, `app/queue/` — one backend per module.
25+# What to cover
2326
24−Business logic lives in services/stores, never in route handlers.
25−
26−## Store roles (do not blur)
27−
28−- **Mongo is authoritative.** If Mongo and ES disagree, Mongo wins.
29−- **ES is best-effort and rebuildable** — never fail an authoritative write on it.
30−- **Redis is a cache** — a Redis outage must degrade, never lose data.
31−- The queue is **in-process and non-durable**; that constraint drives most
32− failure-mode and scaling reasoning. Don't design as if it were durable.
33−
34−## Conventions in brief (see the scoped rules for detail)
35−
36−- `from __future__ import annotations` atop every module; Google-style docstrings
37− (ruff `D`, pydocstyle google). Tunables live in `Settings`, not magic numbers.
38−- Routes are thin; the events routes declare a Pydantic `response_model`
39− (`/health` and `/metrics` are intentionally exempt). Errors map to status
40− codes (Mongo→503, ES→502, queue full→429, shutdown→503).
41−- Tests: pytest with `asyncio_mode=auto`; unit tests are hermetic, Docker-backed
42− tests are marked `integration` and deselected by default.
43−
44−## Docs are a first-class deliverable
45−
46−When you change behavior, update `ARCHITECTURE.md` and `README.md` in the same
47−change. Code and docs must not drift — the architecture doc is graded.
27+Prioritize business logic and error/degradation paths: retry→backoff→DLQ,
28+backpressure (`QueueFull` → 429), cache miss→hit, and graceful degradation when
29+ES/Redis are down. Don't test framework behavior.
4830
