View source on GitHub →

ICN Repo Atlas

Draft interpretive atlas for the full repository record. Mechanical file records are generated by scripts/generate_repo_record.py; this file explains what those records mean.

This is not a replacement for docs/STATE.md, docs/PHASE_PROGRESS.md, or current code. It is the durable map that lets a reader understand the repository as a living system.

Atlas layers

Layer Artifact Purpose
Mechanical record generated/*-file-record.json / .md Every tracked file and directory, mechanically generated
Repo atlas this file Directory families and subsystem placement
Capability map capability-map.md Capabilities, source paths, runtime surfaces, status, blockers
Source-of-truth map source-of-truth-map.md What is canonical/current vs historical/design-direction
Stale/archive map stale-and-archived-map.md What not to treat as current truth
Tool Commons map tool-commons-map.md Base tools vs specialized-suite patterns vs institution bindings
NYCN package map nycn-package-map.md Private/institution-package layer, generated separately with privacy review

Current repo families

The first icn pass should classify every file under these families.

Family Paths Meaning Initial status
Repo control README.md, AGENTS.md, CONTRIBUTING.md, CLAUDE.md, .github/ Operating rules, contribution rules, automation, workflows active
Rust workspace icn/, icn/crates/, icn/apps/, icn/bins/ Main implementation active / uneven maturity
Top-level legacy apps apps/ Earlier app crates not part of current app-topology target likely historical / frozen for new runtime work
Documentation control plane docs/, docs/registry.toml, docs/scripts/ Current docs, registry, validation active
ADR/RFC corpus docs/adr/, docs/rfcs/, ops/coordination/ Decisions, proposals, candidates mixed current/design/historical
Project index docs/reference/project-index/ Orientation and atlas layer active
Public website website/ Public narrative and discovery surface active
Demo/member UI web/pilot-ui/, web/dashboard/, web/api-docs/ Pilot PWA, operator/dashboard/API docs active / demo-oriented
SDKs sdk/typescript/, sdk/react-native/ Client SDKs and mobile-facing foundations TypeScript active; React Native earlier
Institution packages institutions/, institutions/nycn/ In-repo package examples and seed surfaces package-local; boundary-sensitive
Contracts/examples contracts/, examples/ CCL/templates/examples mixed active/example
Deploy/ops deploy/, ops/, monitoring/, docker/, config/, scripts/ Runtime deployment, monitoring, operator tools active ops
Simulations sims/ Modeling and validation experiments research/support
Historical/archive docs/archive/, old planning waves Useful archaeology, not automatic truth historical/stale-risk

Rust workspace families

Family Paths / crates Meaning Notes
Kernel mechanics icn-kernel-api, icn-core, icn-encoding, icn-protocol, icn-services, icn-commons Constraint enforcement, actor/runtime mechanics, encoding, facades Meaning Firewall applies
Identity / crypto / naming / auth icn-identity, icn-crypto, icn-crypto-pq, icn-zkp, icn-authz, icn-naming, icn-steward DIDs, signatures, PQ work, authz, naming, SDIS/steward PQ/autonomy map required
Network / gossip / time icn-net, icn-gossip, icn-time QUIC/TLS, DID-TLS, gossip, vector/logical time service-discovery auth verification gap exists
State / storage / snapshots icn-store, icn-snapshot Sled and restart/snapshot infrastructure restart-survival map required
Ledger / economics icn-ledger, apps/ledger Mutual credit, journal, settlement engine regulatory-safe vocabulary required
Governance / entities / federation icn-governance, icn-entity, icn-coop, icn-community, icn-federation, icn-trust, icn-ccl, apps/governance, apps/membership, apps/charter Strongest implemented institutional layer still contains design/runtime gaps
Runtime API icn-gateway, icn-rpc, icn-api, icn-http-kit REST/WebSocket/gRPC and shared API utilities OpenAPI/types drift matters
Compute / security / privacy / obs icn-compute, icn-security, icn-privacy, icn-obs Trust-gated compute, security, privacy, metrics commons compute map required
Tests icn-testkit, */tests/ Multi-node/store/runtime verification map evidence paths
Binaries icnd, icnctl, icn-console Daemon, CLI, TUI bootstrap/audit/operator surfaces

Classification vocabulary

Use the classification set from full-repo-record.md for every major directory and every important file cluster.

  • implemented
  • implemented but partial
  • feature-gated
  • docs-only/design-direction
  • generated
  • test-only
  • ops-only
  • package-local
  • private-boundary
  • stale/historical
  • contradicted by current code
  • unknown / needs local verification

Next work

  1. Generate the mechanical file record from a checked-out repo.
  2. Commit generated records only after size/privacy review.
  3. Fill this atlas using directory-level summaries first.
  4. Expand into the capability map and stale/archive map.
  5. Repeat for nycn with stricter privacy review.
← Back to Docs