# MoonAtlas Architecture

```text
Mooncakes public endpoints
        |
        v
versioned raw snapshot (external research fetcher)
        |
        v
src/snapshot  -- MoonBit JSON validation, coordinate rules, edge extraction
        |
        v
src/graph     -- MoonBit directed graph, reverse, reachability, SCC, PageRank
        |
        v
src/analysis  -- MoonBit package metrics, rankings, concentration
        |
        v
src/report    -- deterministic text and complete JSON serialization
        |
        +--> cmd/moonatlas (native CLI; stdout or --output)
        +--> web/data/analysis.json
                    |
                    +--> thin HTML/CSS/Canvas visualization
```

## Authority boundaries

- Mooncakes is authoritative for public module and latest-manifest facts at the
  recorded fetch timestamp.
- The raw snapshot is authoritative for one reproducible analysis run.
- `src/snapshot` alone decides whether a dependency key is a valid module
  coordinate. It preserves case and reports invalid values.
- `src/graph` alone owns edge direction and graph algorithms.
- `src/analysis` owns mathematical metrics but does not infer quality, trust,
  security, or maintainer intent.
- Visualization consumes serialized results and must not recompute a competing
  graph in JavaScript.
- Optional Mooncakes metadata is omitted from JSON when absent. The Web detail
  view treats omitted fields as unavailable and does not infer replacements.

## Failure behavior

- Network failures are recorded per manifest by the fetcher and are resumable.
- Invalid JSON or a missing `manifests` object causes a non-zero CLI exit.
- Failed manifest records remain part of requested counts but do not invent
  dependency edges.
- Invalid dependency coordinates are counted and retained in raw source
  evidence; they do not become graph nodes.
- PageRank stops at L1 tolerance `1e-12` or reports the configured iteration
  limit through the analysis result.

## Complexity at current scale

- reverse graph: `O(V + E)`
- one reachability query: `O(V + E)` worst case
- all-package blast radius: `O(V(V + E))` with current exact traversal
- Kosaraju SCC: `O(V + E)`
- PageRank: `O(iterations * (V + E))`

At 2,062 nodes and 2,512 edges, the exact native debug CLI completed the full
analysis in approximately 328 ms on the feasibility machine. This is a measured
local result, not a general performance claim.