Update project documentation and workflow standards

- Add virtual environment requirements and standards to CLAUDE.md - Update README.md with new 00_introduction module overview - Include visual system architecture and dependency analysis features - Document proper development environment setup requirements - Add troubleshooting guidance for environment issues
2026-04-28 22:02:31 -05:00 · 2025-09-16 02:24:42 -04:00
parent 9116e4f256
commit d1943b678a
2 changed files with 97 additions and 15 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -21,11 +21,12 @@ Use descriptive branch names that indicate the type of work:
 - **Experiments**: `experiment/new-testing-approach`

 ### 🔧 Development Workflow
-1. **Create branch** for each logical piece of work
-2. **Make focused commits** related to that branch only
-3. **Test your changes** before committing
-4. **Merge to dev** when feature is complete and tested
-5. **Delete feature branch** after successful merge
+1. **Activate virtual environment** - ALWAYS use `.venv` for consistent dependencies
+2. **Create branch** for each logical piece of work
+3. **Make focused commits** related to that branch only
+4. **Test your changes** before committing
+5. **Merge to dev** when feature is complete and tested
+6. **Delete feature branch** after successful merge

 ### ✅ Commit Standards
 - **One feature per branch** - don't mix unrelated changes
@@ -44,6 +45,7 @@ Use descriptive branch names that indicate the type of work:

 ### 📋 Merge Checklist
 Before merging any feature branch:
+- [ ] Virtual environment activated and dependencies installed
 - [ ] Code works correctly
 - [ ] Tests pass (if applicable)
 - [ ] Documentation updated (if needed)
@@ -52,6 +54,12 @@ Before merging any feature branch:

 ### 🔄 Example Workflow
 ```bash
+# 0. ALWAYS start with virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On macOS/Linux
+# OR: .venv\Scripts\activate  # On Windows
+pip install -r requirements.txt
+
 # 1. Start new feature
 git checkout dev
 git pull origin dev
@@ -82,6 +90,53 @@ git push origin dev
 - **Facilitates rollbacks** - easy to undo specific features if needed
 - **Professional practice** - industry standard for software development

+## 🐍 Virtual Environment Standards - MANDATORY
+
+### 🔐 **ALWAYS Use Virtual Environments**
+**NEVER work directly with system Python or globally installed packages.**
+
+```bash
+# Create virtual environment (one time setup)
+python -m venv .venv
+
+# Activate virtual environment (EVERY session)
+source .venv/bin/activate     # macOS/Linux
+# OR: .venv\Scripts\activate  # Windows
+
+# Install dependencies (after activation)
+pip install -r requirements.txt
+
+# Verify environment
+which python  # Should show .venv path
+pip list      # Should show only project dependencies
+```
+
+### 📋 Virtual Environment Checklist
+**Before ANY development work:**
+- [ ] Virtual environment activated (`source .venv/bin/activate`)
+- [ ] Dependencies installed (`pip install -r requirements.txt`)
+- [ ] Verification: `which python` shows `.venv/bin/python`
+- [ ] Verification: `tito system doctor` shows ✅ environment checks
+
+### 🚫 What NOT to Do
+- ❌ Use system Python for development
+- ❌ Install packages globally with `sudo pip install`
+- ❌ Work without activating `.venv`
+- ❌ Mix dependencies from different environments
+- ❌ Commit with virtual environment deactivated
+
+### 🔧 Environment Troubleshooting
+If you see dependency errors:
+1. **Deactivate and recreate**: `deactivate && rm -rf .venv && python -m venv .venv`
+2. **Reactivate**: `source .venv/bin/activate`
+3. **Reinstall**: `pip install -r requirements.txt`
+4. **Verify**: `tito system doctor`
+
+### 💡 Pro Tips
+- **Add to shell profile**: `alias activate='source .venv/bin/activate'`
+- **Check activation**: Your prompt should show `(.venv)` prefix
+- **Architecture issues**: Use `python -m pip install --force-reinstall` for numpy/architecture conflicts
+
 ## AI Agent Workflow Standards

 ### 🤖 Agent Team Orchestration - Best Practices
@@ -161,7 +216,7 @@ workflow_coordinator.plan_update(module="tensor")
 - Education Architect planning next modules

 **Sequential Tasks (must happen in order):**
- Implementation → Testing → Commit
+- Virtual Environment Setup → Implementation → Testing → Commit
 - Planning → Implementation → Documentation
 - Test Failure → Fix → Re-test → Proceed

--- a/README.md
+++ b/README.md
@@ -60,11 +60,17 @@ Go from "How does this work?" 🤷 to "I implemented every line!" 💪
 - **Visual progress**: Success indicators and system integration
 - **"Aha moments"**: Watch your `ReLU` power real neural networks

+### **📊 NEW: Visual System Architecture**
+- **Interactive dependency graphs**: See how all 17 modules connect
+- **Learning roadmap visualization**: Optimal path through the system
+- **Architecture diagrams**: Complete framework overview
+- **Automated analysis**: Live system statistics and component mapping
+
 ---

 ## 🎯 What You'll Build

-* **One Complete ML Framework** — Not 14 separate exercises, but integrated components building into your own PyTorch-style toolkit
+* **One Complete ML Framework** — Not 17 separate exercises, but integrated components building into your own PyTorch-style toolkit
 * **Fully Functional System** — Every piece connects: your tensors power your layers, your autograd enables your optimizers, your framework trains real networks
 * **Real Applications** — Train neural networks on CIFAR-10 using 100% your own code, no PyTorch imports
 * **Production-Ready Skills** — Complete ML lifecycle: data loading, training, optimization, deployment, monitoring
@@ -74,7 +80,7 @@ Go from "How does this work?" 🤷 to "I implemented every line!" 💪

 ## 🚀 Quick Start (2 minutes)

-### 🧑‍🎓 **Students**
+### 📊 **First Time? Start with the System Overview**

 ```bash
 git clone https://github.com/mlsysbook/TinyTorch.git
@@ -82,8 +88,18 @@ cd TinyTorch
 pip install -r requirements.txt           # Install all dependencies (numpy, jupyter, pytest, etc.)
 pip install -e .                          # Install TinyTorch package in editable mode
 tito system doctor                         # Verify your setup
+
+# 🎯 NEW: Interactive System Architecture Overview
+cd modules/source/00_introduction
+jupyter lab introduction_dev.py           # Explore the complete TinyTorch system visually!
+```
+
+### 🧑‍🎓 **Ready to Build? Start Here**
+
+```bash
+# After exploring the system overview, start building:
 cd modules/source/01_setup
-jupyter lab setup_dev.py                  # Launch your first module
+jupyter lab setup_dev.py                  # Launch your first implementation module
 ```

 ### 👩‍🏫 **Instructors**
@@ -105,7 +121,11 @@ tito nbdev build                          # Update package

 ```
 TinyTorch/
-├── modules/source/           # 16 educational modules
+├── modules/source/           # 17 educational modules
+│   ├── 00_introduction/     # 🎯 NEW: Visual system overview & architecture
+│   │   ├── module.yaml      # Module metadata  
+│   │   ├── README.md        # Getting started guide
+│   │   └── introduction_dev.py  # Interactive visualizations & dependency analysis
 │   ├── 01_setup/            # Development environment setup
 │   │   ├── module.yaml      # Module metadata
 │   │   ├── README.md        # Learning objectives and guide
@@ -149,6 +169,7 @@ TinyTorch/
 ```

 **How It Works:**
+0. **🎯 Start with Overview** - Explore `00_introduction` for visual system architecture and dependencies
 1. **Develop in `modules/source/`** - Each module has a `*_dev.py` file where you implement components
 2. **Export to `tinytorch/`** - Use `tito export` to build your implementations into a real Python package
 3. **Use your framework** - Import and use your own code: `from tinytorch.core.tensor import Tensor`
@@ -157,9 +178,12 @@ TinyTorch/

 ---

-## 📚 Complete Course: 16 Modules
+## 📚 Complete Course: 17 Modules

-**Difficulty Progression:** ⭐ Beginner → ⭐⭐ Intermediate → ⭐⭐⭐ Advanced → ⭐⭐⭐⭐ Expert → ⭐⭐⭐⭐⭐🥷 Capstone
+**Difficulty Progression:** 📊 Overview → ⭐ Beginner → ⭐⭐ Intermediate → ⭐⭐⭐ Advanced → ⭐⭐⭐⭐ Expert → ⭐⭐⭐⭐⭐🥷 Capstone
+
+### **📊 System Overview** (Module 00)
+* **🎯 00_introduction**: Interactive system architecture, dependency visualization, and learning roadmap

 ### **🏗️ Foundations** (Modules 01-05)
 * **01_setup**: Development environment and CLI tools
@@ -185,17 +209,20 @@ TinyTorch/
 ### **🎓 Capstone Project** (Module 16)
 * **16_capstone**: Advanced framework engineering specialization tracks

-**Status**: All 16 modules complete with inline tests and educational content
+**Status**: All 17 modules complete with inline tests and educational content

 ---

 ## 🔗 **Complete System Integration**

-**This isn't 16 isolated assignments.** Every component you build integrates into one cohesive, fully functional ML framework:
+**This isn't 17 isolated assignments.** Every component you build integrates into one cohesive, fully functional ML framework:
+
+**🎯 NEW: Explore the full system architecture visually in Module 00 before diving into implementation!**

 ```mermaid
 flowchart TD
-    A[01_setup<br/>Setup & Environment] --> B[02_tensor<br/>Core Tensor Operations]
+    Z[00_introduction<br/>🎯 System Overview & Architecture] --> A[01_setup<br/>Setup & Environment] 
+    A --> B[02_tensor<br/>Core Tensor Operations]
    B --> C[03_activations<br/>ReLU, Sigmoid, Tanh]
    C --> D[04_layers<br/>Dense Layers]
    D --> E[05_dense<br/>Sequential Networks]