69 lines
4.2 KiB
Markdown
69 lines
4.2 KiB
Markdown
# AGENTS ?? Graph Module
|
|
|
|
## Purpose & Scope
|
|
- Working directories: `src/Graph/StellaOps.Graph.Api`, `src/Graph/StellaOps.Graph.Indexer`, and `src/Graph/__Tests`.
|
|
- Modules covered: Graph API (query/search/paths/diff/overlay/export) and Graph Indexer (ingest, snapshot, overlays).
|
|
- Applicable sprints: `docs-archived/implplan/SPRINT_0207_0001_0001_graph.md`, `docs-archived/implplan/SPRINT_0141_0001_0001_graph_indexer.md`, and follow-on graph documentation tracked in `docs/modules/graph/architecture.md`.
|
|
|
|
## Roles
|
|
- Backend engineer (.NET 10) ??? API, planners, overlays, exports.
|
|
- Data/ETL engineer ??? Indexer ingest, snapshots, overlays.
|
|
- QA/Perf engineer ??? deterministic tests, load/fuzz, offline parity.
|
|
- Docs maintainer ??? graph API/ops runbooks, Offline Kit notes.
|
|
|
|
## Required Reading (treat as read before DOING)
|
|
- `docs/README.md`
|
|
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
|
|
- `docs/modules/platform/architecture-overview.md`
|
|
- `docs/modules/graph/architecture.md`
|
|
- `docs-archived/implplan/SPRINT_0207_0001_0001_graph.md`
|
|
- Sprint doc for current work (e.g., `docs-archived/implplan/SPRINT_0207_0001_0001_graph.md`).
|
|
- Policy overlay contract refs when touching overlays: `POLICY-ENGINE-30-001..003` (see policy module docs).
|
|
|
|
## Determinism & Offline
|
|
- Default to deterministic ordering for streams/exports; manifest checksums required for `graphml/csv/ndjson` exports.
|
|
- Timestamps: UTC ISO-8601; avoid wall-clock in tests.
|
|
- Snapshot/export roots configurable via `STELLAOPS_GRAPH_SNAPSHOT_DIR` or `SbomIngestOptions.SnapshotRootDirectory`.
|
|
- Offline posture: no external calls beyond allowlisted feeds; prefer cached schemas in `.nuget/packages/`.
|
|
|
|
## Data & Environment
|
|
- Storage is currently in-memory (MongoDB dependency removed); persistent backing store to be added in a follow-up sprint.
|
|
- Collections (historical naming) `graph_nodes`, `graph_edges`, `graph_overlays_cache`, `graph_snapshots`, `graph_saved_queries` map to in-memory structures for now.
|
|
- Tenant isolation mandatory on every query and export.
|
|
|
|
## Testing Expectations
|
|
- Unit: node/edge builders, identifier stability, overlay calculators, planners, diff engine.
|
|
- Integration: ingest ??? snapshot ??? query/paths/diff/export end-to-end; RBAC + tenant guards.
|
|
- Performance: synthetic datasets (~500k nodes / 2M edges) with enforced budgets; capture latency metrics.
|
|
- Security: RBAC scopes (`graph:read/query/export`), audit logging, rate limiting.
|
|
- Offline: export/import parity for Offline Kit bundles; deterministic manifests verified in tests.
|
|
|
|
## Observability
|
|
- Metrics to emit: `graph_ingest_lag_seconds`, `graph_tile_latency_seconds`, `graph_query_budget_denied_total`, `graph_overlay_cache_hit_ratio`, clustering counters from architecture doc.
|
|
- Structured logs with trace IDs; traces for ingest stages and query planner/executor.
|
|
|
|
## Coding Standards
|
|
- Target framework: net10.0 with latest C# preview features.
|
|
- Use dependency injection; avoid static singletons.
|
|
- Respect module boundaries; shared libs only if declared in sprint or architecture docs.
|
|
- Naming: projects `StellaOps.Graph.Api`, `StellaOps.Graph.Indexer`; prefer `Graph*` prefixes for internal components.
|
|
|
|
## Coordination & Status
|
|
- Update sprint Delivery Tracker statuses (TODO ??? DOING ??? DONE/BLOCKED) in relevant sprint file.
|
|
- If a required contract/doc is missing or stale, mark the affected task BLOCKED in the sprint and log under Decisions & Risks; do not pause work waiting for live answers.
|
|
|
|
## Run/Test Commands (examples)
|
|
- Restore: `dotnet restore src/Graph/StellaOps.Graph.Api/StellaOps.Graph.Api.csproj`
|
|
- Build: `dotnet build src/Graph/StellaOps.Graph.Api/StellaOps.Graph.Api.csproj -c Release`
|
|
- Tests: `dotnet test src/Graph/__Tests/StellaOps.Graph.Indexer.Tests/StellaOps.Graph.Indexer.Tests.csproj`
|
|
- Lint/style: follow repo-wide analyzers in `Directory.Build.props` / `.editorconfig`.
|
|
|
|
## Evidence
|
|
- Keep artefacts deterministic; attach manifest hashes in PR/sprint notes when delivering exports or snapshots.
|
|
- Document new metrics/routes/schemas under `docs/modules/graph` and link from sprint Decisions & Risks.
|
|
|
|
## Service Endpoints
|
|
- Development: https://localhost:10200, http://localhost:10201
|
|
- Local alias: https://graph.stella-ops.local, http://graph.stella-ops.local
|
|
- Env var: STELLAOPS_GRAPH_URL
|