proposal implemented

Monorepo Hierarchy

Bob Matsuoka Updated 2026-03-11
apex structure monorepo

APEX Monorepo Hierarchy Proposal

Status: DRAFT Author: Robert Matsuoka Date: 2026-02-13 Requested By: Kartik

Summary

Restructure APEX as a monorepo with a 3-level hierarchy: domain/product/initiative. This enables unified product portfolio management with clear traceability from strategic domain down to code repositories.

Proposed Directory Structure

APEX/
├── docs/                           # APEX framework documentation
│   ├── getting-started/
│   ├── concepts/
│   ├── templates/
│   └── schemas/
│
├── products/                       # 3-level hierarchy: domain/product/initiative
│   │
│   ├── applications/               # DOMAIN
│   │   ├── README.md               # Domain overview, all products, all repos roll-up
│   │   ├── gamechanger/            # PRODUCT
│   │   │   ├── README.md
│   │   │   └── initiatives/
│   │   │       ├── 2026-pricing-v3/    # INITIATIVE
│   │   │       │   ├── Initiative.md   # I-2026-XXX artifact
│   │   │       │   ├── repos.yaml      # Linked repositories
│   │   │       │   ├── experiments/
│   │   │       │   └── prds/           # PRDs scoped to this initiative
│   │   │       └── 2026-rate-calendar/
│   │   ├── essentials/             # PRODUCT
│   │   ├── blockbuster/            # PRODUCT
│   │   ├── openspace/              # PRODUCT
│   │   ├── duetto-go/              # PRODUCT
│   │   ├── scoreboard/             # PRODUCT
│   │   └── advance/                # PRODUCT
│   │
│   ├── analytics/                  # DOMAIN
│   │   ├── README.md
│   │   ├── forecasting/            # PRODUCT
│   │   └── ml-platform/            # PRODUCT (internal)
│   │
│   ├── data-platform/              # DOMAIN
│   │   ├── README.md
│   │   ├── demand360/              # PRODUCT (external data source)
│   │   ├── data-pipeline/          # PRODUCT (internal)
│   │   └── infrastructure/         # PRODUCT (internal)
│   │
│   ├── integrations/               # DOMAIN
│   │   ├── README.md
│   │   ├── pms-connectors/         # PRODUCT
│   │   ├── crs-connectors/         # PRODUCT
│   │   └── channel-managers/       # PRODUCT
│   │
│   ├── engineering-platform/       # DOMAIN
│   │   ├── README.md
│   │   ├── security/               # PRODUCT (internal)
│   │   └── monolith/               # PRODUCT (legacy)
│   │
│   └── apex/                       # DOMAIN (meta - APEX itself)
│       ├── README.md
│       └── apex-framework/         # PRODUCT
│           ├── README.md
│           └── initiatives/
│               └── apex-developments/     # Dogfooding initiative (I-2026-APX-001)
│
├── templates/                      # APEX artifact templates
├── schemas/                        # JSON schemas for validation
├── scripts/                        # Automation and tooling
└── .cursor/                        # IDE skills

Hierarchy Levels

Level 1: Domain

Strategic business area grouping products with shared goals.

Domain Description Strategic Owner
applications Customer Facing Applications like GameChanger, GameTime, Advance, HotStats, BlockBuster VP Applications
analytics Forecasting, Pricing, ML Platform & Product Analytics VP Data Science
data-platform Tools and platform that applications re-use and that drive time-to-value and consistency - e.g. Integration Platform, Canonical Data Model, Metrics Platform, Onboarding Tools VP Product Platform
integrations Integrations to PMS / CRS / Rate Shopping / etc. VP Product Platform
engineering-platform Tools used by developers to deliver the product consistently - Infrastructure, shared services VP Engineering
apex APEX framework itself (dogfooding) CTO

Level 2: Product

Discrete product with its own roadmap, team, and P&L.

Product Type Examples Characteristics
Customer GameChanger, DuettoGo External users, revenue-generating
Internal ML Platform, Data Pipeline, Infrastructure, Security Enables other products
Legacy Monolith Migration target

Level 3: Initiative

Time-bounded effort that delivers customer/business value.

Field Description
Initiative.md APEX artifact (I-YYYY-NNN) with goals, metrics, status
repos.yaml List of repositories linked to this initiative
experiments/ Related experiments (E-YYYY-NNN)
prds/ PRDs scoped to this initiative

Repository Linking Strategy

repos.yaml Format

# products/applications/gamechanger/initiatives/2026-pricing-v3/repos.yaml
initiative: I-2026-042
product: gamechanger
domain: applications

repositories:
  - name: duetto-pricing-engine
    url: https://github.com/duettoresearch/duetto-pricing-engine
    role: primary          # primary | supporting | dependency | shared
    team: pricing-team

  - name: duetto-rate-service
    url: https://github.com/duettoresearch/duetto-rate-service
    role: supporting
    team: pricing-team

  - name: duetto-monolith
    url: https://github.com/duettoresearch/duetto
    role: dependency
    paths:                 # Specific paths within monolith
      - src/main/java/com/duetto/pricing/
      - src/main/java/com/duetto/rate/

Roll-Up Mechanism

Product README automatically aggregates all repos from its initiatives:

## Linked Repositories

| Repository | Initiative | Role | Team |
|------------|------------|------|------|
| duetto-pricing-engine | I-2026-042 | primary | pricing-team |
| duetto-rate-service | I-2026-042 | supporting | pricing-team |
| duetto-calendar-ui | I-2026-043 | primary | frontend-team |

Domain README aggregates all repos from all products:

## Applications Repositories

### GameChanger (8 repos)
- duetto-pricing-engine (I-2026-042)
- duetto-rate-service (I-2026-042)
...

### BlockBuster (5 repos)
- duetto-groups-service (I-2026-051)
...

**Total: 23 repositories across 4 products**

README Templates

Domain README Template

# {Domain Name}

**Strategic Owner:** {Name}
**Products:** {count}
**Repositories:** {count}

## Overview

{Domain description and strategic goals}

## Products

| Product | Type | Status | Initiatives | Repos |
|---------|------|--------|-------------|-------|
| [GameChanger](./gamechanger/) | Customer | Active | 3 | 8 |
| [Essentials](./essentials/) | Customer | Active | 1 | 4 |

## All Repositories

{Auto-generated roll-up from all product initiatives}

## Key Metrics

{Domain-level OKRs and metrics}

Product README Template

# {Product Name}

**Domain:** [{domain}](../)
**Product Owner:** {Name}
**Tech Lead:** {Name}
**Status:** {Active | Maintenance | Sunset}

## Overview

{Product description, target users, value proposition}

## Initiatives

| Initiative | Status | Timeline | Repos |
|------------|--------|----------|-------|
| [I-2026-042: Pricing V3](./initiatives/2026-pricing-v3/) | delivery | Q1-Q2 | 3 |
| [I-2026-043: Rate Calendar](./initiatives/2026-rate-calendar/) | discovery | Q2 | 1 |

## All Repositories

| Repository | Latest Initiative | Role | Team |
|------------|-------------------|------|------|
| duetto-pricing-engine | I-2026-042 | primary | pricing-team |
| duetto-rate-service | I-2026-042 | supporting | pricing-team |

PRDs live under each initiative (e.g. `initiatives/2026-pricing-v3/prds/`).

Initiative README Template

# Initiative: {Title}

**ID:** I-YYYY-NNN
**Product:** [{product}](../../)
**Domain:** [{domain}](../../../)
**Status:** {discovery | validated | delivery | deployed | learning | success | killed}

## Linked Repositories

{Contents of repos.yaml rendered as table}

## Artifacts

- [Initiative.md](./Initiative.md) - Initiative specification
- [repos.yaml](./repos.yaml) - Repository manifest
- [prds/](./prds/) - PRDs scoped to this initiative

## Experiments

{List of related experiments}

Migration Plan

Phase 1: Structure Creation (Week 1)

  1. Create products/ directory with domain subdirectories
  2. Create product directories for all 8 customer products + internal platforms
  3. Add README templates at each level

Phase 2: Initiative Migration (Week 2)

  1. Move existing initiatives/ content into appropriate product directories
  2. Create repos.yaml for each initiative
  3. Link to existing JIRA epics

Phase 3: Repository Mapping (Week 3)

  1. Map all 152 repositories to products via initiatives
  2. Generate roll-up READMEs
  3. Create automation scripts for README generation

Phase 4: Validation (Week 4)

  1. Verify all repos are linked
  2. Validate product ownership
  3. Train teams on new structure

Automation Requirements

1. README Generator Script

# Generate all roll-up READMEs from repos.yaml files
python scripts/generate-readmes.py

2. Repository Validator

# Ensure all repos in org are linked to at least one initiative
python scripts/validate-repo-coverage.py

3. JIRA Sync

# Sync initiative status with JIRA epics
python scripts/sync-jira-initiatives.py

Product Inventory (Current)

Customer-Facing Products

Product Domain Repos (Est.) Status
GameChanger applications ~15 Active
Essentials applications ~5 Active
BlockBuster applications ~8 Active
OpenSpace applications ~6 Active
Demand360 data-platform ~4 Active
ScoreBoard applications ~3 Active
Advance applications ~5 Active
Duetto Go applications ~2 Active

Internal Products

Product Domain Repos (Est.) Status
ML Platform analytics ~10 Active
Forecasting analytics ~8 Active
Pricing analytics Active
Data Pipeline data-platform ~12 Active
Infrastructure data-platform ~15 Active
Security engineering-platform ~5 Active
PMS Connectors integrations ~20 Active
CRS Connectors integrations ~10 Active
Channel Managers integrations ~8 Active
Monolith engineering-platform 1 (1.2M LOC) Legacy

Meta Products

Product Domain Repos Status
APEX Framework apex 1 Active

Open Questions

  1. Shared Repositories: How to handle repos that serve multiple products?

  2. Proposal: Link to multiple initiatives with role: shared

  3. Monolith Paths: How to track which monolith paths belong to which product?

  4. Proposal: Use paths: field in repos.yaml for granular mapping

  5. Historical Initiatives: Import past initiatives or start fresh?

  6. Proposal: Start fresh, link to JIRA for historical context

  7. Cross-Domain Products: Products that span multiple domains?

  8. Proposal: Primary domain assignment with cross-references

Approval

  • [ ] Kartik - Architecture approval
  • [ ] Bob - CTO approval
  • [ ] Product Owners - Product mapping validation

This document is DRAFT and subject to revision based on feedback.