Project File Tree & Architecture Overview

This document describes the directory layout and architectural organization for the Deep Learning project boilerplate template.

.
├── .github/                 # GitHub repository workflows and CI/CD pipelines
│   └── workflows/           # GitHub Actions workflow definitions
├── .gitignore               # Git ignore rules for virtualenvs, logs, data, and weights
├── .pre-commit-config.yaml  # Pre-commit hook configuration for Ruff linting & formatting
├── CITATION.cff             # Machine-readable citation file (BibTeX / GitHub / Zenodo integration)
├── README.md                # Project README and quickstart guide
├── agents/                  # AI agent skills, prompts, and workspace automation
│   └── skills/              # Specialized AI agent skills
│       ├── convert-to-dl-template/  # Skill to migrate existing codebases into this boilerplate
│       ├── dl-experiment-runner/    # Skill to automate hyperparameter sweeps & experiment reporting
│       ├── dl-model-exporter/       # Skill to export PyTorch models to ONNX/TorchScript
│       └── dl-paper-to-code/        # Skill to implement academic papers into modular components
├── assets/                  # Documentation assets, figures, and presentation materials
│   ├── documents/           # Project specs, whitepapers, and paper drafts
│   ├── figures/             # Diagram graphics, performance plots, architecture charts
│   └── logos/               # Project logos and branding assets
├── docker/                  # Containerization setup for GPU environment reproducibility
│   ├── Dockerfile           # Base CUDA/PyTorch container definition
│   └── docker-compose.yml   # Multi-GPU / volume mount service configuration
├── docs/                    # Project documentation, API references, and guides
│   ├── blog/                # Research blog posts & release updates
│   ├── gen_ref_pages.py     # Automatic API reference generator script for src/ modules
│   ├── file-tree.md         # Project file tree & architecture overview (this file)
│   ├── index.md             # Documentation site homepage
│   ├── getting-started.md   # Setup & first training run guide
│   ├── requirements.md      # Hardware, software, CUDA, & PyTorch requirements
│   ├── agent-skills.md      # AI & Agentic Coding skills overview & usage guide
│   ├── docker-guide.md      # Docker hot-reloading & volume mount external control guide
│   ├── versioning.md        # Automatic versioning, tag releases, and mike docs guide
│   ├── references.md        # Literature references & mathematical formulations
│   ├── community.md         # Contribution guidelines & community standards
│   └── citation-contact.md  # Citation guidelines (BibTeX, APA) and author contact
├── inputs/                  # Isolated directory for raw input data and experiment configs
│   ├── backbones/           # Pretrained foundation model checkpoints / raw weights
│   ├── datasets/            # Raw and preprocessed dataset files
│   └── experiments/         # Specific experiment override YAML configuration files
├── logs/                    # Training and evaluation logs (ignored by git except .gitkeep)
├── main.py                  # Quick workspace validation script
├── properdocs.yml            # ProperDocs site configuration & navigation
├── notebooks/               # Interactive notebooks for EDA, prototyping, and visualization
│   ├── jupyter/             # Standard Jupyter notebooks (.ipynb)
│   └── marimo/              # Reactive Marimo notebooks (.py)
├── outputs/                 # Output artifacts generated by runs (ignored by git except .gitkeep)
│   ├── artifacts/           # Exported models (ONNX, TorchScript), inference outputs, plots, and metrics JSONs
│   └── weights/             # Model's zoo and saved model checkpoints (.pt, .ckpt, .safetensors)
├── scripts/                 # Executable entrypoint scripts for core project workflows
│   ├── train.py             # Model training script
│   ├── finetune.py          # Model fine-tuning & transfer learning script
│   ├── evaluate.py          # Model evaluation & benchmarking script
│   └── inference.py         # Batch and single-sample inference script
├── src/                     # Core source code directory
│   └── tensoris/            # Core Tensoris Python package
│       ├── backend/         # Execution engines, training components, and objectives
│       │   ├── callbacks/   # Checkpointing, early stopping, LR schedulers, W&B logging
│       │   ├── components/  # Neural network sub-building blocks
│       │   │   ├── blocks/  # Multi-layer building blocks (e.g., ResidualBlock, TransformerEncoder)
│       │   │   ├── layers/  # Custom neural network layers (e.g., Attention, Normalization)
│       │   │   └── stages/  # Multi-block architecture stages (e.g., BackboneStage)
│       │   ├── losses/      # Custom loss functions and compound objective criteria
│       │   ├── metrics/     # Domain-specific evaluation metrics and scoring functions
│       │   └── trainers/    # Execution engines & training loops
│       ├── configs/         # Base configuration schemas and defaults
│       ├── data/            # Data loading logic, PyTorch Datasets, DataLoaders, and transforms
│       ├── dependencies/    # External library wrappers and third-party integrations
│       ├── lib/             # Shared core utilities
│       │   ├── core/        # Core primitives and constants
│       │   ├── io/          # File I/O, serialization, and cloud storage utilities
│       │   └── utils/       # Helper functions, logging setups, and seed fixers
│       └── models/          # Top-level neural network architectures and full model wrappers
├── temp/                    # Temporary scratch directory (ignored by git except .gitkeep)
├── tests/                   # Automated test suite
│   ├── e2e/                 # End-to-end integration and pipeline tests
│   ├── integration/         # Inter-component integration tests
│   └── unit/                # Fast unit tests for layers, metrics, models, and utils
└── toolkit/                 # Developer tooling, CLI helpers, and code generation scripts

---

Directory Roles & Architectural Guidelines

1. src/tensoris/ Package Architecture

• src/tensoris/models/: Houses full model definitions. A model here combines backbones, custom components, and prediction heads into a unified API.
• src/tensoris/backend/: Contains execution mechanisms and structural primitives:
• components/: Modular sub-architectures (layers, blocks, stages).
• trainers/: Training and validation step execution logic.
• callbacks/: Event hooks for logging, early stopping, and checkpoint management.
• losses/ & metrics/: Objective functions and validation metrics.
• src/tensoris/data/: Encapsulates PyTorch Dataset, DataLoader, data cleaning, and augmentation transforms.
• src/tensoris/configs/: Stores base config definitions and schema validation logic.
• src/tensoris/lib/: Contains shared low-level helpers (core, io, utils).

2. Workflow Scripts (scripts/ vs main.py)

• scripts/ contains standard CLI entrypoints (train.py, finetune.py, evaluate.py, inference.py).
• main.py serves as a quick sanity check script to verify the workspace setup.

3. Data & Artifact Isolation (inputs/ & outputs/)

• All raw datasets, pretrained weights, and experiment overrides live in inputs/.
• All generated checkpoints, exported artifacts, and logs live in outputs/ and logs/.
• .gitkeep files ensure directory structure is tracked in git while heavy binary contents are excluded via .gitignore.

4. Package Build System & Environment Management (uv & pyproject.toml)

• Package Build Backend: pyproject.toml is configured with hatchling as the build system:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

This allows src/ to be installed cleanly as an editable Python package (uv pip install -e .), enabling absolute imports (e.g. from src.models import ...) across all scripts without manually tweaking PYTHONPATH.

• Recommended Toolchain (uv): Developers are strongly encouraged to use uv for unified Python versioning, virtual environment management, and deterministic dependency locking:
• Python Versioning: Pin python runtime via uv python pin 3.11 (tracked in .python-version).
• Virtual Environment: Create isolated environment via uv venv.
• Dependency Management: Add and sync dependencies reproducibly via uv add <package> and uv sync (tracked in pyproject.toml and uv.lock).
• Editable Local Install: Install project source in editable mode with uv pip install -e ..