| 1 | # AI Agent Docs Entrypoint |
| 2 | |
| 3 | This folder is the **starting point for AI agents** making code changes in this repo. |
| 4 | |
| 5 | ## Read This First |
| 6 | |
| 7 | 1. `docs/architecture/ARCHITECTURE.md` (existing system architecture) |
| 8 | 2. `docs/architecture/MAP.md` (existing system map) |
| 9 | 3. `docs/architecture/DEPLOYMENT.md` (runtime stack, ports, env, persistence) |
| 10 | 4. `docs/architecture/DATA_FLOWS.md` (critical request + job + data flows) |
| 11 | 5. `docs/integrations/ADDING_A_CONNECTOR.md` (exact connector extension checklist) |
| 12 | |
| 13 | ## Fast Repo Orientation (Code Pointers) |
| 14 | |
| 15 | - Backend entrypoint: `backend/copilot.py` |
| 16 | - Backend router registration: `backend/copilot.py`, `backend/app/routers/*.py` |
| 17 | - DB bootstrap + seed logic: `backend/app/db/db_setup.py`, `backend/app/db/db_populate.py` |
| 18 | - Connector registry + verify dispatch: `backend/app/connectors/services.py` |
| 19 | - Connector DB lookup helper: `backend/app/connectors/utils.py` |
| 20 | - Auth routes + JWT handling: `backend/app/auth/routes/auth.py`, `backend/app/auth/utils.py` |
| 21 | - Scheduler init + job mapping: `backend/app/schedulers/scheduler.py` |
| 22 | - Scheduler APIs: `backend/app/schedulers/routes/scheduler.py` |
| 23 | - Incident alert/case paths: `backend/app/incidents/routes/incident_alert.py`, `backend/app/incidents/routes/db_operations.py`, `backend/app/incidents/services/db_operations.py` |
| 24 | - MinIO data store operations: `backend/app/data_store/data_store_operations.py`, `backend/app/data_store/data_store_setup.py`, `backend/app/data_store/data_store_session.py` |
| 25 | - Frontend API client base: `frontend/src/api/httpClient.ts` |
| 26 | - Frontend connector endpoints + UI: `frontend/src/api/endpoints/connectors.ts`, `frontend/src/views/Connectors.vue`, `frontend/src/components/connectors/*` |
| 27 | |
| 28 | ## Agent Guardrails |
| 29 | |
| 30 | - Prefer editing the smallest set of files that completes the task. |
| 31 | - When adding backend functionality, wire all layers explicitly: |
| 32 | 1. service/util |
| 33 | 2. route |
| 34 | 3. router include |
| 35 | 4. top-level include in `backend/copilot.py` |
| 36 | - When adding user-facing connector features, update both: |
| 37 | - backend endpoint(s) |
| 38 | - frontend endpoint wrapper + UI wiring |
| 39 | - Verify any change affecting auth, scheduler, or storage paths with focused tests/manual API calls. |
| 40 | |
| 41 | ## Common Starting Commands |
| 42 | |
| 43 | ```bash |
| 44 | rg --files backend/app |
| 45 | rg --files frontend/src |
| 46 | rg -n "include_router|APIRouter" backend/app |
| 47 | rg -n "connector|verify" backend/app/connectors frontend/src |
| 48 | ``` |