ores.codegen architecture

projects/ores.codegen/
├── library/
│   ├── component_catalogue.org  # Component → models-dir/glob/modeling-dir (read by manifest.py)
│   ├── data/                # Static data (licences, modelines)
│   │   ├── licence-GPL-v3.txt
│   │   └── modeline.org     # Editor modelines — MASD-style org, read directly by core.py
│   └── templates/           # Mustache templates + the ores.* physical-space
│                             # graph (root -> technical space -> facet ->
│                             # archetype), one org node per graph element,
│                             # tangled to the .mustache files alongside them
│       ├── ores.*.org       # Physical-space graph nodes (root/ts/facet/archetype)
│       ├── sql_*.mustache
│       └── doc_*.org.mustache
├── models/                  # Legacy JSON model files (being migrated to org)
│   └── <component>/         # e.g. refdata/, trade/, dq/, iam/
├── output/                  # Default destination for generated files
├── scripts/                 # Shell scripts for common operations
├── src/                     # Python source
│   ├── codegen/             # CLI package (codegen.py entry point)
│   │   ├── __init__.py
│   │   ├── cli.py           # argparse entry point; dispatches subcommands
│   │   ├── core.py          # Model classification, rendering, output resolution
│   │   ├── generate.py      # generate / regenerate subcommand implementations
│   │   ├── org_loader.py    # Parses org-mode model files (entity/junction/...)
│   │   ├── physical_space.py # Loads the ores.* graph; computes supported/target sets
│   │   ├── manifest.py      # Named component registry
│   │   ├── list_cmd.py      # =list= subcommand
│   │   ├── diff_cmd.py      # =diff= subcommand
│   │   └── migrate_*.py     # One-off JSON → org migration scripts, per model type
│   ├── doc_generate.py      # v2 information-architecture doc generator
│   ├── fpml_parser.py       # FPML Genericode XML → JSON models
│   ├── images_generate_sql.py
│   ├── lei_extract_subset.py
│   └── iso_generate_metadata_sql.py
├── modeling/
│   └── ores.codegen.org     # Component model (the entry point)
├── docs/
│   ├── architecture.org     # This document
│   ├── cpp_generation_analysis.md
│   └── doc_generator.md
├── requirements.txt
├── codegen.sh               # Wrapper: activates venv and calls codegen.py
├── generate_doc.sh          # Wrapper for doc_generate.py
└── generate_*_schema.sh     # Legacy per-component schema scripts (being retired)

In src/codegen/core.py (model classification and rendering) and src/codegen/physical_space.py (graph traversal):

• get_model_type(filename, path=None) — classify a model file's type (domain_entity, junction, schema, field_group, …). Org models are classified via their #+type: frontmatter first; filename-suffix predicates (is_junction_model, …) are the fallback for legacy JSON models with no frontmatter. The table type (and its is_table_model predicate) was retired once every entity migrated to domain_entity — see Retire legacy codegen profile system; add junction support to physical-space codegen.
• load_graph(templates_dir) (in physical_space.py) — parse the ores physical-space graph org nodes into a Graph of technical spaces, facets, and archetypes.
• compute_supported_set(properties, graph, model_type) — the archetypes an entity can generate, from facet #+model_types: plus the entity's :ores.*.enabled: drawer overrides.
• compute_target_set(address, graph) — the archetypes to generate this run: all facets under an --address, or every facet if none given.
• resolve_targets(model_path, base_dir, address, properties=)= (in generate.py) — the single resolver used by both the CLI and the compass wrapper; combines supported ∩ target into concrete (template, output path) units. See Addressing system below for how address narrows the target set.
• resolve_output_path(pattern, model_data, model_type) — expand an output path pattern using model fields.
• render_template(template_path, data) — render a Mustache template with the given data.
• generate_from_model() — orchestrate generation for one model file.

• Mustache via the pystache library.
• Templates live in library/templates/. The .mustache files are generated artefacts, tangled from the literate facet docs in the same directory — see the Codegen template library overview for the hierarchy, tangle workflow, and drift checks.
• Output is SQL, C++, or org-mode depending on the template family.

• library/data/licence-GPL-v3.txt — full GPL v3 licence text used in generated headers.
• library/data/modeline.org — per-language editor modeline strings (MASD-style org hierarchy; read directly by core.py via _load_modelines_from_org()).

This section covers the legacy JSON model path only — org-mode models (the current standard; see Codegen input org-file schema reference) declare their type via #+type: frontmatter instead of a filename suffix, and get_model_type() checks that frontmatter first. Filename-suffix detection, described below, is the fallback used only for JSON models that carry no frontmatter.

Each legacy JSON type has a root JSON key of the same name and is associated with one or more templates through the ores physical-space graph.

The *_table.json=/=*_table.org table model type (root key table, sql_schema_create.mustache) is retired — every SQL-only entity table migrated to domain_entity and the type's dispatch was removed from the generator entirely.

The active mapping is declared in ores physical-space graph, not hard-coded in Python. Each facet entry lists which templates apply to which model types and the output path pattern.

The physical-space address is the selector: every entity's generation footprint is its supported set on the ores physical-space graph (root → technical space → facet → archetype), narrowed by --address to a subtree of that graph and by the model's own :ores.*.enabled: drawer overrides. There is no separate profile declaration to maintain — an entity's ores.* binding is its generation footprint.

Examples: --address ores.sql.schema generates SQL DDL only; --address ores.cpp generates every C++ facet (domain, generator, repository, service, protocol, …); --address ores.cpp.qt generates just the Qt facet; omitting --address generates an entity's full supported set.

Named components are declared in library/component_catalogue.org, read directly by src/codegen/manifest.py at startup. See component_catalogue.org for the full 16-component table (name, models_dir, entity_glob, exclude_suffix, modeling_dir).

The following shell scripts have been deleted and replaced by codegen.sh:

From library/data/modeline.org:

• Licence generation. Generated files carry a licence header with editor modelines, a copyright with the current year, and the appropriate per-language comment formatting.
• Multi-language comment support. SQL and C++ use /* ... */ with a * = line prefix; Python uses =""", JavaScript uses /** */.
• Graph-resolved output. Each archetype's output path pattern (on its ores physical-space graph node) is expanded against the model's own fields and written project-root-relative; parent directories are created automatically. --dry-run prints the resolved paths without writing.
• Overall models. A model.json can orchestrate generation of multiple artefacts in dependency order.
• Dynamic prefixing. A model_name property on an overall model prefixes every output file (for example solvaris_).
• Automatic sibling loading. JSON models in the same directory are loaded together so a template can cross-reference them.
• Enhanced data context. Subject-area datasets (such as currencies_dataset, countries_dataset) are surfaced as named variables to templates for direct access.

From models/slovaris/catalogs.json:

[
    {
        "name": "Slovaris",
        "description": "Imaginary world to test all system functions.",
        "owner": "Testing Team"
    }
]

The sql_catalog_populate.mustache template generates SQL that:

1. Includes the enhanced licence header.
2. Sets the schema to ores.
3. Generates SQL calls to metadata.upsert_dq_catalogs().
4. Includes summary queries.

To add a new SQL-only entity table (the table model type's retired role) for an existing component, scaffold a domain_entity model (compass add entity_org --component <name> ...) with no ** Qt section instead — see Codegen input org-file schema reference.

To add a new facet or template:

1. Add the Mustache template to library/templates/.
2. Add an entry to ores physical-space graph under the relevant facet heading, adding a row to the templates table with template, output pattern, and optionally model_types.
3. If adding a new model type, update get_model_type() in src/codegen/core.py and add any preprocessing logic in the generate_from_model() dispatch block.

To add a new named component:

1. Add a row to library/component_catalogue.org with the component's models_dir, entity_glob, exclude_suffix, and modeling_dir.
2. The component is then available as codegen.sh regenerate --component <name>.