gitrusprusandCursor
0543694c1e
Introduce AGENTS.md, platform rule, and add-parser-adapter skill for contracts-first adapter workflow. Co-authored-by: Cursor <cursoragent@cursor.com>
50 lines
1.9 KiB
Plaintext
50 lines
1.9 KiB
Plaintext
---
|
|
description: MapMil platform architecture, boundaries, and agent workflow
|
|
alwaysApply: true
|
|
---
|
|
|
|
# MapMil Platform
|
|
|
|
Monorepo: **ЦА** (analytics) + **ЦП** (parsing) + **contracts** + **ПИ** (distribution API).
|
|
|
|
## Data flow
|
|
|
|
```
|
|
CA admin → Redis cp:jobs:{family} → CP adapter → POST /internal/ingest → CA DB → map / ПИ
|
|
```
|
|
|
|
| Center | Path | Role |
|
|
|--------|------|------|
|
|
| ЦА API | `centers/analytics/api/` | FastAPI, ingest, scheduler, admin |
|
|
| ЦА UI | `centers/analytics/frontend/` | Vue + Leaflet admin |
|
|
| ЦП | `centers/parsing/workers/` | Adapter registry, batch + Telegram listener |
|
|
| Contracts | `contracts/` | Shared schemas — change first |
|
|
|
|
## Hard boundaries
|
|
|
|
- ЦП **never** touches CA database — only `POST /internal/ingest` and `PATCH /internal/jobs/{id}`
|
|
- `source_type` events must match adapter type; stable `source_url` required (CA dedup)
|
|
- `source_config` validated via `contracts/sources.py` on admin CRUD
|
|
- Telegram session: `data/telegram.session` — local only, **never commit**
|
|
- `.env` and secrets — **never commit**
|
|
|
|
## CP adapter model
|
|
|
|
Each `source_type` implements `SourceAdapter.run(job_id, source_config, *, ctx) -> tuple[list[dict], str | None]`.
|
|
|
|
Output dicts are `IngestEventItem`-shaped. Routing: `contracts/queues.py` (`SOURCE_FAMILY` → `cp:jobs:{telegram|web|nlp}`).
|
|
|
|
Worker images: `cp-workers` (telegram), `cp-workers-web` (crawl4ai), `cp-workers-nlp` (viina).
|
|
|
|
## Agent workflow
|
|
|
|
1. **Contracts first** if data shape or routing changes
|
|
2. **One zone per task** — do not mix contracts + UI + infra in one unfocused change
|
|
3. **Follow existing adapters** — copy `viina.py` or `telegram.py`, not greenfield
|
|
4. **Do not touch** Telegram listener unless explicitly asked
|
|
5. **Verify**: `docker compose config`, then targeted service rebuild
|
|
|
|
Docs: `README.md`, `centers/parsing/ARCHITECTURE.md`, `AGENTS.md`.
|
|
|
|
For new `source_type`: use skill `add-parser-adapter`.
|