Repository Concern Lines

This document is the practical map of the major concern lines inside NEXUS.

Use it when deciding:

  • where a new decision belongs
  • where a new concept note belongs
  • which branch a change should live on
  • whether work is foundational or specific to one domain or platform

Current Concern Lines

NEXUS Core

Scope:

  • the meaning of NEXUS itself
  • ontology boundaries
  • cross-project principles
  • core vocabulary
  • FORGE direction for functionalizing repeated work into deterministic reviewed surfaces
  • Event Modeling tool direction and its relationship to FORGE and FnTools

Primary docs:

Typical branch names:

  • nexus-core
  • ontology-imprint-alignment

Engineering Conventions

Scope:

  • F# modeling practices
  • testing strategy
  • documentation conventions
  • explicit allowlists and deterministic coding rules
  • default durable UTC time handling with localization in views

Primary docs:

Typical branch names:

  • engineering-conventions
  • testing-foundation

Repository Governance

Scope:

  • branch topology
  • project-memory structure
  • terminology governance
  • decision-record discipline

Primary docs:

Typical branch names:

  • repository-governance
  • terminology-governance

Ingestion And Canonical History

Scope:

  • raw acquisition
  • canonical observed history
  • projections
  • graph derivation and materialization
  • export-window analysis

Primary docs:

Typical branch names:

  • ingestion-foundation
  • export-window-analysis
  • graph-materialization

LOGOS Intake And Handling

Scope:

  • source systems
  • intake channels
  • signal kinds
  • pools
  • sensitivity, sharing, sanitization
  • access context and rights policy

Primary docs:

Typical branch names:

  • logos-intake-foundation
  • public-safe-publication
  • rights-aware-intake

Interaction And UI

Scope:

  • FnHCI
  • FnUI
  • live capture UX
  • later NEXUS user-facing interaction surfaces

Primary docs:

Typical branch names:

  • fnhci-foundation
  • fnui-foundation
  • live-capture-foundation

External Integrations

Scope:

  • Talkyard
  • Discord
  • GitHub
  • forum/wiki/issue-tracker connections
  • scrape vs API reconciliation

Primary docs:

Typical branch names:

  • talkyard-integration
  • discord-integration
  • github-ingestion

App And Tool Lines

Scope:

  • concrete product and tool lines built on top of NEXUS
  • application-domain modeling beyond the platform foundation
  • branding/division boundaries that affect branch shape and documentation placement

Examples:

  • Cheddar
  • CheddarBooks
  • LaundryLog within CheddarBooks
  • PerDiemLog within CheddarBooks
  • FnTools
  • FnAPI.Penpot and FnMCP.Penpot within FnTools
  • Event Modeling tooling and Penpot integration work within FnTools
  • future CheddarBooks support/debugging flows
  • other downstream applications

Primary docs:

Typical branch names:

  • cheddar-foundation
  • cheddarbooks-foundation
  • cheddarbooks-laundrylog-tool
  • cheddarbooks-support-model
  • fntools-foundation
  • penpot-integration

How To Use This Map

For documentation:

  • put the decision where its concern line lives
  • if a change spans concern lines, place the main decision in the dominant line and cross-link from the others

For branching:

  • start from main for short focused work
  • use a longer-running branch only when a concern line is still actively evolving across multiple merges
  • if a subtask clearly belongs under an active concern-line branch, branch from that concern-line branch instead of directly from main

For AI and human onboarding:

  1. read README.md
  2. read this concern-line map
  3. read docs/glossary.md
  4. read the decision records and how-to docs for the relevant concern line
  5. then inspect source and tests

Near-Term Implementation Plan

  1. Keep README.md and NEXUS-Code/README.md linked to this map.
  2. Continue naming branches by workstream or concern line, not by agent/tool.
  3. When new decisions are added, sanity-check which concern line they belong to before writing them.
  4. When FnHCI/FnUI and external integrations grow, give them their own explicit architecture docs rather than burying them under ingestion notes.
  5. Add a grouped index for docs/decisions/ later if the decision set grows enough to need another navigation layer.