Skip to content

Organization Architecture

The Shoonya Organization is the logical root for Anuva engineering work. It does not require its own repository. It gives every repository a place in the larger operating model.

The organization model separates slow-moving engineering process from faster-moving product planning and implementation.

flowchart TD
  org["Shoonya Organization"]

  org --> platform["Engineering Platform"]
  org --> video["Product: Video Creator"]
  org --> realtime["Future Product: Realtime"]

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

  video --> videoMain["anuva-main-video-creator"]
  videoMain --> project["Anuva Video Creator\nGitHub Project"]
  videoMain --> web["anuvax-cms"]
  videoMain --> python["anuva-python-server"]
  videoMain --> unity["anuva-unity-video-creator"]
  project --> web
  project --> python
  project --> unity

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

Layer Responsibilities

Layer Owns Does Not Own
Organization Logical grouping, naming, and governance model. Product implementation details.
Engineering Platform Shared engineering standards, Codex workflows, templates, prompts, registries, handbook structure, and aggregated docs publishing. Product roadmaps or product-specific implementation plans.
Product Product vision, roadmap, product architecture, product capability map, GitHub Project coordination, cross-repository planning, playbooks, and releases. Shared engineering standards or low-level implementation details.
Product repository Code, local docs, tests, verification, and repository-specific implementation decisions. Organization-wide process or product-level roadmap.

Dependency Direction

Products consume Engineering Platform standards. Implementation repositories consume both Engineering Platform standards and product-level direction.

flowchart LR
  handbook["anuva-engineering-handbook"] --> productMain["product-main repository"]
  handbook --> implementation["implementation repository"]
  productMain --> project["GitHub Project"]
  project --> implementation
  implementation --> devDocs["anuva-dev-docs"]
  productMain --> devDocs

  handbook -. "shared process" .-> implementation
  productMain -. "product task context" .-> project

The intended dependency direction is one-way:

  • Engineering Platform defines how Shoonya engineers software.
  • Product Management repositories define what a product is trying to accomplish.
  • Implementation repositories define how their bounded component is built.

Product Main Pattern

Each product can have one product-main repository when it needs durable product coordination.

flowchart TD
  product["Product"] --> main["product-main repository"]
  main --> roadmap["Roadmap"]
  main --> architecture["Product architecture"]
  main --> capabilities["Product capability map"]
  main --> playbooks["Product playbooks"]
  main --> releases["Product releases"]
  main --> repoTasks["Repository impact and tasks.yml"]
  repoTasks --> github["GitHub issues and project items"]
  github --> repos["Implementation repositories"]
  repos --> github

The current example is anuva-main-video-creator. A future Realtime product should follow the same shape with anuva-main-realtime when it is ready.

Why This Model Exists

Engineering process should be stable and reusable. Product work changes more frequently as roadmap, features, and implementation plans evolve.

This separation lets Shoonya:

  • Improve Codex-based engineering workflows once and reuse them across products.
  • Add new products without copying handbook content.
  • Keep product-main repositories focused on product coordination.
  • Keep implementation repositories focused on code and local technical context.
  • Track cross-repository execution through GitHub Projects instead of chat memory.
  • Publish development docs through anuva-dev-docs without moving source docs out of their owning repositories.
  • Route Codex sessions to the correct repository for each type of work.

Routing Summary

Task Type Start In
Change shared Codex process, AGENTS.md guidance, templates, prompts, or registry rules. anuva-engineering-handbook
Plan a product feature, roadmap item, product ADR, release, or cross-repository product change. Product Management repository, such as anuva-main-video-creator
Create or sync product implementation issues and project board status. anuva-main-video-creator
Implement, test, or document a repository-specific technical change. Owning implementation repository
Build and publish aggregated development docs. anuva-dev-docs
Add a new product. Engineering Platform for the pattern, then the new product-main repository for product-specific content