Proposed project structure (please review / discuss)

[Polichinel]

Proposed directory structure + separation-of-concerns model for views-pipeline-core.

This is not a final decision — asking for alignment + input before locking this in as our reference structure.

---

Core structural principles

1) Managers (managers/)

• Orchestrate multiple modules
• Handle high-level workflows
• Coordinate across parts of the system
• Manage config + state
• Example: MappingManager coordinates data handlers + visualization modules + path utils

2) Modules in dedicated dirs

• Pure business logic
• Single responsibility
• No orchestration of other modules
• Reusable + testable in isolation
• Example: visualization/maps/interactive.py only generates Plotly maps

3) Core vs Infrastructure

• core/ — domain objects, no external deps
• All other dirs — implementation details/infra

4) Separation of concerns

concern	dir
file/storage i/o	io/
data manipulation / validation	data/
visualization logic	visualization/
orchestration	managers/
external services	integrations/

---

Proposed layout

views-pipeline-core/
├── README.md
├── pyproject.toml
├── .gitignore
│
├── .github/
│   └── workflows/
│
├── documentation/
│   ├── README.md
│   └── ADRs/
│
├── tests/
│   ├── unit/
│   │   ├── test_data/
│   │   ├── test_models/
│   │   ├── test_ensembles/
│   │   └── test_managers/
│   ├── integration/
│   └── fixtures/
│
└── views_pipeline_core/
    ├── __init__.py
    │
    ├── core/
    │   ├── __init__.py
    │   └── exceptions.py
    │
    ├── data/
    │   ├── __init__.py
    │   ├── loaders.py
    │   ├── datasets.py
    │   ├── validators.py
    │   └── transformers.py
    │
    ├── io/
    │   ├── __init__.py
    │   ├── files.py
    │   ├── storage.py
    │   └── serialization.py
    │
    ├── managers/
    │   ├── __init__.py
    │   ├── datastore.py
    │   ├── model.py
    │   ├── ensemble.py
    │   ├── logging.py
    │   └── mapping.py
    │
    ├── visualization/
    │   ├── __init__.py
    │   ├── maps/
    │   │   ├── __init__.py
    │   │   ├── interactive.py
    │   │   ├── static.py
    │   └── reports/
    │       ├── __init__.py
    │       ├── utils.py
    │       └── templates/
    │
    ├── modeling/
    │   ├── __init__.py
    │   ├── training.py
    │   ├── evaluation.py
    │   ├── prediction.py
    │   ├── drift.py
    │   └── catalogs/
    │       ├── __init__.py
    │       └── registry.py
    │
    ├── ensembles/
    │   ├── __init__.py
    │   ├── aggregation.py
    │   ├── reconciliation.py
    │   └── validators.py
    │
    ├── integrations/
    │   ├── __init__.py
    │   ├── wandb/
    │   │   ├── __init__.py
    │   │   └── client.py
    │   └── appwrite/
    │       ├── __init__.py
    │       └── client.py
    │
    ├── cli/
    │   ├── __init__.py
    │   ├── commands/
    │   └── utils.py
    │
    ├── assets/
    │   ├── shapefiles/
    │   │   ├── country/
    │   │   └── priogrid/
    │   └── templates/
    │
    ├── configs/
    │   ├── __init__.py
    │   └── schemas/
    │
    └── utils/
        ├── __init__.py
        ├── validation.py
        └── decorators.py

---

Discussion prompt

Request:
→ Are we aligned on this as the baseline structure before we start migrating modules?

Specifically looking for:

• objections
• missing categories
• any “cross-cutting” logic placement concerns (e.g. caching)
• naming tweaks

If no blocking objections, I propose we mark this as “accepted baseline” and file sub-issues for refactoring of views_pipeline_core into this shape.