Skip to content

Repository Architecture

Anuva is organized as a layered engineering system under the logical Shoonya Organization. The Engineering Platform defines shared process and standards. Product Management repositories coordinate products. Product implementation repositories own code and local technical documentation.

This handbook represents the Engineering Platform. It is not the Product Management repository for Video Creator or any future product.

flowchart TD
  org["Shoonya Organization"] --> platform["Engineering Platform"]
  org --> products["Products"]

  platform --> handbook["anuva-engineering-handbook"]
  platform --> sharedSkills["future: anuva-shared-skills"]
  platform --> sharedStandards["future: anuva-shared-standards"]
  platform --> devDocs["anuva-dev-docs"]
  platform --> docsPortal["candidate: anuva-docs-portal"]

  products --> video["Video Creator"]
  products --> realtime["future: Realtime"]

  video --> videoMain["anuva-main-video-creator"]
  videoMain --> web["anuvax-cms"]
  videoMain --> python["anuva-python-server"]
  videoMain --> unity["anuva-unity-video-creator"]

  realtime --> realtimeMain["future: anuva-main-realtime"]
  realtimeMain --> realtimeUnity["future: anuva-unity-realtime"]

Architectural Intent

The repository architecture should let Shoonya add products without redefining the engineering operating model each time.

The stable ideas are:

  • The Shoonya Organization is the logical root.
  • The Engineering Platform owns reusable engineering process, standards, templates, prompts, registries, and Codex operating guidance.
  • Each product has a Product Management repository when product-level coordination becomes substantial.
  • Product implementation repositories own code, local architecture, tests, and technical docs.
  • Capabilities are named independently from repositories so ownership can move without renaming the capability.
  • The handbook stays product-agnostic and links to product repositories for product-specific planning.

Repository Layers

Layer Repository Role
Organization No repository required Logical root for Shoonya-wide engineering and product structure.
Engineering Platform anuva-engineering-handbook Defines shared engineering process, repository architecture, capability ownership, Codex workflows, templates, prompts, and handbook publishing structure.
Engineering Platform anuva-dev-docs Aggregates MkDocs output from Anuva repositories, generates project status pages, and publishes the static development docs site through Cloudflare Pages.
Engineering Platform anuva-shared-skills Future optional home for reusable skills if they need independent versioning.
Engineering Platform anuva-shared-standards Future optional home for standards if they need independent versioning.
Engineering Platform anuva-docs-portal Candidate future publishing layer only if anuva-dev-docs outgrows its current static publishing role.
Product Management anuva-main-video-creator Product and program management for Video Creator. Owns product roadmap, product architecture, product capability map, cross-repository planning, product ADRs, playbooks, and releases.
Product implementation anuvax-cms Owns Web App implementation and local implementation documentation for Video Creator.
Product implementation anuva-python-server Owns Python server implementation and local implementation documentation for Video Creator.
Product implementation anuva-unity-video-creator Owns Unity Video Creator implementation and local implementation documentation.
Product Management anuva-main-realtime Future Product Management repository for Realtime.
Product implementation anuva-unity-realtime Future Realtime implementation repository.

Topology Rules

flowchart LR
  engineering["Engineering Platform"] --> standards["Shared standards"]
  engineering --> workflows["Shared workflows"]
  engineering --> templates["Templates and prompts"]
  engineering --> publishing["Docs publishing"]

  standards --> productMain["Product Management repository"]
  workflows --> productMain
  templates --> productMain
  publishing --> devDocs["anuva-dev-docs"]

  productMain --> roadmap["Product roadmap"]
  productMain --> productArchitecture["Product architecture"]
  productMain --> featurePlans["Cross-repository feature plans"]
  productMain --> githubProject["GitHub Issues and Project"]

  featurePlans --> implementation["Product implementation repositories"]
  implementation --> localDocs["Local docs, code, tests, verification"]
  localDocs --> devDocs
  githubProject --> implementation
Rule Meaning
Engineering Platform owns reusable process Shared Codex workflows, AGENTS.md design, templates, prompts, and registry rules start here.
Product Management owns product coordination Product vision, roadmap, product architecture, release planning, product ADRs, and cross-repository feature planning live in product-main repositories.
Implementation repositories own implementation Code-level architecture, tests, local commands, and operational details stay with the owning implementation repository.
GitHub Projects track execution Product-main repositories create GitHub issues and project items for implementation work; implementation repositories update issues, PRs, and project fields as work progresses.
anuva-dev-docs publishes discoverable docs Each repository owns its source docs, while anuva-dev-docs builds and publishes aggregated static HTML for discovery.
Product examples stay lightweight The handbook may use Video Creator or Realtime to explain hierarchy, but it should not become their implementation guide.
Registries record routing Repository and capability registries should tell Codex where work starts and where durable ownership lives.

Product Management Boundary

Product Management repositories are coordination repositories, not code repositories.

For example, anuva-main-video-creator may define a Video Creator feature, split it into repository-specific tasks, and track release readiness. It should not own the Web, Python, or Unity implementation details that belong in anuvax-cms, anuva-python-server, and anuva-unity-video-creator.

sequenceDiagram
  participant H as Engineering Handbook
  participant P as Product Main
  participant R as Implementation Repository

  H->>P: Provides shared process, templates, and prompts
  P->>P: Defines product-level feature and repository impact
  P->>R: Creates GitHub issue as repository-specific handoff
  R->>R: Implements, tests, and updates local docs
  R->>P: Reports completion through PR, issue, and project status
  P->>H: Requests registry updates only when shared ownership changes

GitHub Project Coordination

Video Creator work is coordinated through anuva-main-video-creator and the Anuva Video Creator GitHub Project.

flowchart LR
  main["anuva-main-video-creator"] --> feature["Feature docs"]
  feature --> impact["RepositoryImpact.md"]
  impact --> tasks["tasks.yml and HandoffPrompts.md"]
  tasks --> issues["GitHub issues"]
  issues --> project["Anuva Video Creator GitHub Project"]
  project --> web["anuvax-cms"]
  project --> python["anuva-python-server"]
  project --> unity["anuva-unity-video-creator"]
  web --> project
  python --> project
  unity --> project
  project --> progress["Progress.md and ReviewChecklist.md"]

The GitHub issue is the durable handoff packet. Codex chat may help generate it, but the issue and product-main docs are the source of truth for implementation work.

Documentation Publishing

Each Anuva repository owns its own Markdown source docs and MkDocs configuration. anuva-dev-docs owns the aggregated static site.

flowchart TD
  handbook["anuva-engineering-handbook\nMkDocs site"] --> publisher["anuva-dev-docs"]
  main["anuva-main-video-creator\nMkDocs site"] --> publisher
  web["anuvax-cms\nMkDocs site"] --> publisher
  python["anuva-python-server\nMkDocs site"] --> publisher
  unity["anuva-unity-video-creator\nMkDocs site"] --> publisher
  project["GitHub Project data"] --> status["project-status.html"]
  status --> publisher
  publisher --> cloudflare["Cloudflare Pages\nanuva.girishd.com"]

anuva-dev-docs should skip repositories that are not yet MkDocs-enabled and report that skip clearly. The absence of MkDocs setup in one repository should not block publishing the repositories that are ready.

Repository Lifecycle

stateDiagram-v2
  [*] --> Proposed
  Proposed --> Candidate: documented in registry
  Candidate --> Active: repository created and onboarded
  Active --> Split: responsibility outgrows boundary
  Active --> Archived: no longer maintained
  Split --> Active: new ownership recorded
  Archived --> [*]

Current Direction

  • anuva-engineering-handbook remains the Engineering Platform source of truth.
  • anuva-dev-docs is the active aggregated development docs publisher.
  • anuva-main-video-creator is the active Product Management repository for Video Creator.
  • anuvax-cms, anuva-python-server, and anuva-unity-video-creator remain Video Creator implementation repositories.
  • anuva-main-realtime is the expected Product Management pattern for a future Realtime product.
  • anuva-docs-portal is only a candidate future publishing layer if the current anuva-dev-docs model needs to split into a larger portal product.
  • Optional shared Engineering Platform repositories should be extracted only when their responsibilities need independent versioning, ownership, or release cadence.