From 62cf7a03adef276d60734d30aa9251b3865ecf75 Mon Sep 17 00:00:00 2001
From: anntr1k3 <abogdanov2k5@ya.ru>
Date: Fri, 3 Jul 2026 13:21:24 +0400
Subject: [PATCH] Add contributor map and align backend version

---
 .gitignore              |  1 +
 README.md               |  1 +
 backend/main.py         |  2 +-
 backend/pyproject.toml  |  2 +-
 docs/contributor-map.md | 76 +++++++++++++++++++++++++++++++++++++++++
 5 files changed, 80 insertions(+), 2 deletions(-)
 create mode 100644 docs/contributor-map.md

diff --git a/.gitignore b/.gitignore
index f2e4ed1..301acd4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -205,6 +205,7 @@ graphify-out/
 docs/*
 !docs/OUTBOUND_DATA.md
 !docs/production-hardening.md
+!docs/contributor-map.md
 !docs/mesh/
 docs/mesh/*
 !docs/mesh/threat-model.md
diff --git a/README.md b/README.md
index e453c75..19b150d 100644
--- a/README.md
+++ b/README.md
@@ -1014,6 +1014,7 @@ The platform is optimized for handling massive real-time datasets:
 <details>
 <summary>📁 Project Structure</summary>
 
+New contributors can use [docs/contributor-map.md](docs/contributor-map.md) for a shorter orientation guide.
 
 ```
 Shadowbroker/
diff --git a/backend/main.py b/backend/main.py
index 14099f3..191727f 100644
--- a/backend/main.py
+++ b/backend/main.py
@@ -15,7 +15,7 @@ from dataclasses import dataclass, field
 from typing import Any
 from json import JSONDecodeError
 
-APP_VERSION = "0.9.82"
+APP_VERSION = "0.9.83"
 
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
diff --git a/backend/pyproject.toml b/backend/pyproject.toml
index a91f012..2835243 100644
--- a/backend/pyproject.toml
+++ b/backend/pyproject.toml
@@ -57,7 +57,7 @@ dev = ["pytest>=9.0.3", "pytest-asyncio>=1.4.0", "ruff>=0.9.0", "black>=24.0.0"]
 
 [tool.ruff.lint]
 # The current backend carries historical style debt in large legacy modules.
-# Keep CI focused on actionable correctness checks for the v0.9.82 release.
+# Keep CI focused on actionable correctness checks for the v0.9.83 release.
 ignore = ["E401", "E402", "E701", "E731", "E741", "F401", "F402", "F541", "F811", "F841"]
 
 [tool.black]
diff --git a/docs/contributor-map.md b/docs/contributor-map.md
new file mode 100644
index 0000000..5486573
--- /dev/null
+++ b/docs/contributor-map.md
@@ -0,0 +1,76 @@
+# Contributor Map
+
+ShadowBroker is a monorepo. The fastest way to contribute is to pick one
+surface, keep the change small, and run the matching test slice before opening
+a pull request.
+
+## Main Areas
+
+| Area | Path | Stack | Start here when |
+| --- | --- | --- | --- |
+| Web dashboard | `frontend/` | Next.js, React, MapLibre | Changing UI behavior, map layers, panels, client-side API code, or tests |
+| Backend API | `backend/` | FastAPI, Python | Changing API routes, data shaping, local auth gates, or feed orchestration |
+| Desktop app | `desktop-shell/` | Tauri, TypeScript, Rust | Changing packaged desktop runtime behavior or native bridge code |
+| Privacy core | `privacy-core/` | Rust | Changing low-level cryptographic or privacy primitives |
+| Deployment | `docker-compose*.yml`, `helm/`, `.github/` | Docker, Helm, GitHub Actions | Changing packaging, CI, images, or cluster deployment |
+| Agent package | `openclaw-skills/` | Python skill package | Changing OpenClaw/agent integration helpers |
+
+## Low-Risk First Contributions
+
+- Documentation fixes that make setup, architecture, or operations clearer.
+- Small frontend utilities with focused tests under `frontend/src/__tests__/`.
+- Isolated UI components outside the large map shell.
+- Version or metadata consistency fixes across package manifests.
+- Backend tests that document existing behavior without changing live-data paths.
+
+## Areas That Need Extra Care
+
+These paths are security-sensitive or operationally sensitive and have explicit
+owners in `.github/CODEOWNERS`:
+
+- `backend/auth.py`
+- `backend/services/mesh/`
+- `backend/services/fetchers/`
+- `.github/workflows/`
+- Docker Compose, Helm, and CI/deploy files
+- `frontend/src/i18n/`
+
+Changes there are welcome, but expect stricter review and a stronger test plan.
+
+## Large Files To Avoid For First PRs
+
+Some files are intentionally central and carry a lot of historical behavior.
+Avoid broad edits in these until you have a narrow bug or test target:
+
+- `frontend/src/components/MaplibreViewer.tsx`
+- `frontend/src/components/MeshTerminal.tsx`
+- `frontend/src/components/SettingsPanel.tsx`
+- `frontend/src/components/NewsFeed.tsx`
+- `backend/main.py`
+- `backend/routers/ai_intel.py`
+- `backend/routers/mesh_public.py`
+
+Prefer extracting or testing a small behavior around them instead of rewriting
+the file.
+
+## Test Slices
+
+Run the smallest relevant check locally, then expand if the change touches a
+shared contract.
+
+```bash
+# Backend targeted tests
+(cd backend && uv sync --frozen --group dev)
+(cd backend && uv run pytest tests/path/to_test.py -q)
+
+# Frontend targeted tests
+(cd frontend && npm ci)
+(cd frontend && npx vitest run src/__tests__/path/to_test.ts)
+
+# Full PR checks from CONTRIBUTING.md
+pytest backend/tests/
+(cd frontend && npx vitest run)
+```
+
+If a change touches live-data APIs, fetchers, or unattended deployments, also
+review `docs/production-hardening.md` and note the result in the PR template.