System Architecture

app/
├── main.py                      # Entry point + navigation setup
│
├── content/                     # Self-contained page modules
│   ├── home/                   # Session management
│   ├── dataset/                # Dataset configuration with tabs
│   ├── model/                  # Model architecture builder
│   ├── training/               # Training configuration
│   ├── monitor/                # Live training monitoring
│   ├── results/                # Results & evaluation
│   └── interpret/              # Model interpretability
│
├── components/                  # Shared UI components (flat structure)
│   ├── header.py               # App header with session info
│   ├── sidebar.py              # Configuration status sidebar
│   ├── theme.py                # Theme customization
│   ├── styling.py              # CSS injection
│   └── utils.py                # GPU detection, utilities
│
├── state/                       # Session state management
│   ├── workflow.py             # ML workflow state
│   ├── ui.py                   # UI preferences
│   ├── cache.py                # Cached operations
│   ├── session_state.py        # Session utilities
│   └── persistence.py          # File-based persistence
│
├── models/                      # PyTorch model architectures
│   ├── base.py                 # Abstract base class
│   ├── pytorch/
│   │   ├── cnn_builder.py     # Custom CNN builder
│   │   ├── transfer.py        # Transfer learning models
│   │   └── transformer.py     # Vision Transformer
│   └── manual/                 # Manual implementations
│
├── training/                    # Training infrastructure
│   ├── engine.py               # Core training loop
│   ├── worker.py               # Background training
│   ├── dataset.py              # PyTorch Dataset & DataLoader
│   ├── transforms.py           # Image transformations
│   ├── optimizers.py           # Optimizer & scheduler factory
│   └── evaluator.py            # Model evaluation
│
└── utils/                       # Utility functions
    ├── dataset_utils.py        # Dataset scanning
    ├── dataset_viz.py          # Visualizations
    └── checkpoint_manager.py   # Model checkpointing

# content/dataset/page.py
from components.header import render_header
from components.sidebar import render_sidebar
from content.dataset import view

render_header()
render_sidebar()
view.render()

# ✅ CORRECT
from state.workflow import get_dataset_config, save_dataset_config
config = get_dataset_config()
save_dataset_config(new_config)

# ❌ WRONG
config = st.session_state.dataset_config
st.session_state.dataset_config = new_config

def _run_training(session_id: str, experiment_id: str):
    # Get configs from files (thread-safe)
    experiment = get_experiment_from_file(session_id, experiment_id)
    model_config = get_model_from_file(session_id, experiment['model_id'])
    
    # Build model and train
    model = build_model(model_config)
    engine = TrainingEngine(...)
    results = engine.fit(epochs=epochs)
    
    # Write results to file (thread-safe)
    write_experiment_update(session_id, experiment_id, results)

class BaseModel(ABC):
    def __init__(self, config: Dict[str, Any]):
        self.config = config
        self.model = None
    
    @abstractmethod
    def build(self) -> nn.Module:
        pass
    
    @abstractmethod
    def get_parameters_count(self) -> Tuple[int, int]:
        pass

@st.fragment(run_every="1s")
def live_training_monitor():
    if not is_training_active():
        return
    
    # Get latest metrics from file
    results = get_results()
    
    # Display live metrics
    col1, col2, col3 = st.columns(3)
    col1.metric("Epoch", results.get("epoch", 0))
    col2.metric("Loss", f"{results.get('loss', 0):.4f}")
    col3.metric("Accuracy", f"{results.get('accuracy', 0):.2%}")

.streamlit_sessions/
└── {session_id}/
    ├── session.json       # Session metadata
    ├── dataset.json       # Dataset configuration
    ├── models.json        # Model configurations
    ├── training.json      # Training configurations
    └── experiments.json   # Experiment results

checkpoints/
└── {experiment_id}/
    ├── checkpoint_epoch_10.pth
    ├── checkpoint_epoch_20.pth
    └── best_model.pth     # Best model by validation loss

@st.cache_data(ttl=300)
def scan_dataset_directory(base_path: str) -> dict[str, Any]:
    """Expensive dataset scanning - cached for 5 minutes"""
    # ...
    
@st.cache_resource
def load_trained_model(model_path: str):
    """Singleton model loading - loaded once per session"""
    return torch.load(model_path)

# Global registry for active training engines
_active_engines: dict[str, TrainingEngine] = {}
_training_threads: dict[str, threading.Thread] = {}

class MyCustomModel(BaseModel):
    def build(self) -> nn.Module:
        # Build your model
        return model
    
    def get_parameters_count(self) -> Tuple[int, int]:
        total = sum(p.numel() for p in self.model.parameters())
        trainable = sum(p.numel() for p in self.model.parameters() 
                       if p.requires_grad)
        return total, trainable

st.Page("content/my_page/page.py", title="My Page", icon="🆕")