Add Cursor agent guidance for MapMil platform development.

Introduce AGENTS.md, platform rule, and add-parser-adapter skill for contracts-first adapter workflow. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-14 12:44:06 +03:00
parent 8fbabd3c11
commit 0543694c1e
3 changed files with 291 additions and 0 deletions
@@ -0,0 +1,100 @@
+# MapMil — guide for AI agents
+
+Quick orientation for Cursor and other coding agents working in this repository.
+
+## What this is
+
+**MapMil** is a monorepo platform: parsing center (ЦП) collects events from external sources, analytics center (ЦА) stores them and serves a map + admin UI, external consumers (ПИ) read via distribution API.
+
+```
+ЦА (centers/analytics)  ←→  Redis  ←→  ЦП (centers/parsing)
+         ↓ ingest                              ↑ adapters
+    PostgreSQL + map UI                   Telegram / Crawl4AI / VIINA
+         ↓
+    GET /api/v1/events → ПИ
+```
+
+## Repository map
+
+| Path | Stack | Purpose |
+|------|-------|---------|
+| `contracts/` | Pydantic | `ingest`, `jobs`, `sources`, `queues` — shared truth |
+| `centers/analytics/api/` | FastAPI, SQLAlchemy | Admin API, ingest, scheduler, map queries |
+| `centers/analytics/frontend/` | Vue 3, Leaflet | Map, parsers, events, analytics, consumers |
+| `centers/parsing/workers/` | Python async | CP workers, adapter registry, LLM extract |
+| `docker-compose.yml` | Docker | `ca-*`, `cp-workers*`, `redis` |
+| `data/` | Telethon session | **Gitignored** — do not commit |
+
+## Commands
+
+```bash
+cp .env.example .env          # then set TELEGRAM_API_ID/HASH, optional DEEPSEEK_API_KEY
+docker compose up --build     # full stack → http://localhost:8080
+docker compose config         # validate compose
+docker compose up --build cp-workers-web   # single worker rebuild
+```
+
+Health: `curl http://localhost:8080/api/health`
+
+Create Telegram parser:
+
+```bash
+curl -X POST http://localhost:8080/admin/jobs \
+  -H 'Content-Type: application/json' \
+  -d '{"source_type":"telegram","source_config":{"channel":"example","limit":50}}'
+```
+
+## Conventions
+
+### Contracts-first
+
+Any change to event shape, `source_config`, or queue routing starts in `contracts/`, then CA/CP/UI.
+
+### CP adapters
+
+- Protocol: `workers/adapters/base.py` (`SourceAdapter`)
+- Registry: `workers/adapters/registry.py` (`ENABLED_ADAPTERS`)
+- Queue family: `contracts/queues.py` (`SOURCE_FAMILY`)
+- Config schema: `contracts/sources.py` (`CONFIG_MODELS`)
+
+### Ingest output
+
+Adapters return dicts matching `IngestEventItem` (`contracts/ingest.py`). Required: `source_url`. Dedup in CA by `source_url`.
+
+### LLM extract (runtime, not dev)
+
+`extract_mode: llm` uses DeepSeek via `workers/llm_extract.py`. Key: `DEEPSEEK_API_KEY` in `.env`. Do not confuse with Cursor dev agents.
+
+## Common tasks
+
+| Task | Start here | Skill |
+|------|------------|-------|
+| New parser source | `contracts/sources.py` | `add-parser-adapter` |
+| Admin API change | `centers/analytics/api/app/routers/` | — |
+| Map / UI | `centers/analytics/frontend/src/` | — |
+| New worker image | `docker-compose.yml` + `requirements-*.txt` | `add-parser-adapter` |
+
+## Do not
+
+- Commit `.env`, `data/`, or API keys
+- Add direct DB access from CP workers
+- Change `IngestEventItem` without checking ingest + map + ПИ impact
+- Modify Telegram listener/session logic unless the task requires it
+- Reintroduce legacy root `backend/` or `frontend/` (removed; use `centers/`)
+
+## Cursor setup
+
+- Rule: `.cursor/rules/platform.mdc` (always on)
+- Skill: `.cursor/skills/add-parser-adapter/` for end-to-end new sources
+- Deep docs: `README.md`, `centers/parsing/ARCHITECTURE.md`
+
+## Commit style
+
+Follow existing history — imperative, concise:
+
+```
+Add CP source adapter registry with multi-worker queues and LLM extract.
+Add Telegram listener, scheduler, and extended parsers admin UI.
+```
+
+One logical change per commit; do not bundle unrelated zones.