# Architecture

## Purpose

Code Parser Service owns source parsing, graph extraction, technical commit diff, and graph delta computation.

## Boundaries

- **Redis consumers:** `files.changed`, `repo.snapshot.ready`, `commits.changed`
- **Language analyzers:** centralized registry in `internal/service/parser/registry/` with Go, JavaScript/TypeScript, Python, Java, PHP, HTML/templates, CSS, and tiered fallback parsing
- **Framework detectors:** React, Next.js, Vue, Angular, FastAPI, Flask, Spring, Laravel, Symfony, WordPress
- **Graph artifacts:** MongoDB (`code_graph_artifacts`, `snapshot_graphs`) with automatic chunking for payloads above the BSON document limit
- **Redis producers:** `chunks.ready`, `graph.artifact.ready`, `parser.diagnostics.ready`, `graph.delta.ready`
- **REST:** health/readiness + debug control plane (`/parse-jobs`, `/artifacts`, `/diagnostics`)
- No Git sync or commit-level narrative analysis — that is Commit Intelligence

## Runtime flow

```text
files.changed (code)
  → consumer (code-parser-service group)
  → parser orchestration (worker pool)
  → Go analyzer
  → ArtifactStore (MongoDB; chunked when large)
  → publisher (graph.artifact.ready, chunks.ready)

commits.changed
  → consumer
  → commit diff resolution (event changed_files or git fallback)
  → load base/target artifacts from ArtifactStore
  → compute graph delta
  → save delta artifact + publish graph.delta.ready
```

See [`events.md`](events.md) for stream contracts and [`observability.md`](observability.md) for structured logs.

## Large graph artifacts

MongoDB enforces a **16 MB BSON document limit**. Per-file graphs (`code_graph_artifacts`) and merged snapshot graphs (`snapshot_graphs`) are stored as:

1. **Inline** — one manifest document with `nodes` and `edges` when the payload fits under `MONGO_ARTIFACT_MAX_PART_MB` (default `10` MB per part).
2. **Chunked** — a manifest document (`chunked: true`, `part_count`, `node_count`, `edge_count`) plus rows in `code_graph_artifact_parts` or `snapshot_graph_parts`.

Reads reassemble parts transparently; `artifact_id` and `mongo://` URIs are unchanged. See [`local-setup.md`](local-setup.md) for `MONGO_ARTIFACT_MAX_PART_MB`.

## Dependencies

- **Repo Sync** publishes `files.changed` and clones repos to `GIT_WORKSPACE_PATH`
- **Redis** for stream transport
- Local contracts in `internal/contracts/` (shared module deferred)