Rustelo/docs/architecture/foundation-dependency-analysis.md

# Foundation Dependency Analysis - COMPLETE MAPPING

## CIRCULAR DEPENDENCIES IDENTIFIED

### 1. CORE CIRCULAR DEPENDENCY CHAIN
```
tools → core-lib → components → tools
```

**Details:**
- `tools/Cargo.toml` depends on `core-lib` for shared functionality
- `core-lib/build.rs` uses `tools::build::PathResolver` and comprehensive analysis
- `components/build.rs` uses `tools::comprehensive_analysis::generate_components_documentation` 
- `tools` provides build-time analysis that `core-lib` and `components` consume

### 2. BUILD-TIME CIRCULAR DEPENDENCY CHAIN  
```
server → tools → shared → server
pages → tools → shared → pages  
```

**Details:**
- `server/build.rs` uses `tools::build::PathResolver` and `tools::comprehensive_analysis::generate_server_documentation`
- `pages/build.rs` uses `tools::build::run_pages_scaffolding` and comprehensive analysis
- `tools` depends on `shared` for types and utilities
- `shared` may reference server/pages components through generated code

### 3. CLIENT BUILD DEPENDENCY ISSUES
```
client/build.rs → external tools (pnpm, node) → CSS generation → client
```

**Details:**
- Client build runs `pnpm run build` for CSS processing
- CSS processing depends on UnoCSS config and package.json
- Generated CSS affects client compilation
- Creates external dependency cycle through Node.js toolchain

## ALL BUILDERS IDENTIFIED AND ANALYSIS

### 1. **client/build.rs** - CSS BUILD COORDINATOR
```rust
fn coordinate_css_build(output_path: &Path, source_paths: &[PathBuf]) -> Result<bool, String>
fn run_direct_css_build()
```
**Purpose:** 
- Manages CSS compilation via UnoCSS/Tailwind
- Coordinates pnpm install and build processes
- Handles freshness checking for CSS files
- **Problem:** External dependency on Node.js toolchain breaks isolation

### 2. **pages/build.rs** - PAGE SCAFFOLDING GENERATOR  
```rust
build_page_generator::generate_page_components()
tools::build::run_pages_scaffolding()
tools::comprehensive_analysis::generate_pages_documentation()
```
**Purpose:**
- Generates page component implementations
- Creates scaffolding for new pages
- Generates page documentation
- **Problem:** Depends on tools crate, creates circular dependency

### 3. **components/build.rs** - COMPONENT DOCUMENTATION GENERATOR
```rust
fn generate_documentation_with_cache() -> Result<bool, Box<dyn std::error::Error>>
fn try_use_smart_cache() -> Result<bool, Box<dyn std::error::Error>>
```
**Purpose:**
- Generates comprehensive component documentation
- Implements smart caching system (L1/L2/L3 cache)
- Tracks component dependencies for cache invalidation
- **Problem:** Heavy dependency on tools crate for caching and analysis

### 4. **server/build.rs** - SERVER ROUTE DOCUMENTATION
```rust
fn generate_server_documentation() -> Result<(), Box<dyn std::error::Error>>
```  
**Purpose:**
- Analyzes server-side API routes
- Generates route documentation and TOML configuration
- Documents route definitions and handlers
- **Problem:** Uses tools::build::PathResolver and comprehensive analysis

### 5. **core-lib/build.rs** - DISABLED CODE GENERATION
```rust
// PHASE 3.4: Code generation has been completely disabled in favor of
// pure trait-based runtime resolution. This build script now only
// provides configuration checks.
```
**Purpose:** 
- Previously generated shared resources
- Now disabled in favor of trait-based resolution
- Only provides configuration checks
- **Status:** Correctly PAP compliant, no builders used

## ENVIRONMENT VARIABLE DEPENDENCIES

### Client Build Environment Variables:
- `SKIP_CSS_BUILD` - Skip CSS compilation
- `CARGO_MANIFEST_DIR` - Build context
- **External:** `pnpm`, `node` executables required

### Pages Build Environment Variables:
- `SKIP_SCAFFOLDING_BUILD` - Skip page scaffolding  
- `SKIP_DOCS_BUILD` - Skip documentation generation
- `SITE_INFO_PATH` - Documentation output path
- `TARGET` - Compilation target

### Components Build Environment Variables:
- `SKIP_DOCS_BUILD` - Skip documentation generation
- `SITE_INFO_PATH` - Documentation output path
- `CARGO_MANIFEST_DIR` - Build context
- `FORCE_REBUILD_CACHE` - Force cache invalidation
- `SITE_DEVTOOLS_PATH` - Cache directory path

### Server Build Environment Variables:
- `SITE_INFO_PATH` - Documentation output path
- `CARGO_MANIFEST_DIR` - Build context

### Shared/Core Environment Variables:
- `SKIP_SHARED_RESOURCES_BUILD` - Skip resource generation

## CODE GENERATION POINTS

### 1. **Active Code Generation:**
- `client/build.rs` → CSS files (`public/website.css`)
- `pages/build.rs` → Page components and documentation
- `components/build.rs` → Component documentation with caching
- `server/build.rs` → Route documentation and TOML configs

### 2. **Disabled Code Generation:**
- `core-lib/build.rs` → Completely disabled (PAP compliant)

### 3. **Generated Output Locations:**
- `public/website.css` - Generated by client build
- `target/site_build/info/` - Generated documentation
- Page component files - Generated by pages build
- Route configuration files - Generated by server build

## ROOT CAUSE ANALYSIS

### 1. **Tools Crate as Central Dependency Hub**
The `tools` crate has become a central dependency that creates circular references:
- Provides build-time utilities that all other crates need
- Contains comprehensive analysis functionality
- Implements smart caching system
- **Solution:** Break tools into smaller, focused trait-based crates

### 2. **Build-time vs Runtime Confusion**  
Current architecture mixes build-time and runtime concerns:
- Build scripts generate code that affects runtime behavior
- Runtime traits depend on build-time generated content
- **Solution:** Pure runtime resolution without build-time generation

### 3. **External Toolchain Dependencies**
Client build depends on external Node.js toolchain:
- Breaks Rust-only compilation model
- Creates unpredictable build environment requirements
- **Solution:** Rust-only CSS processing or optional external dependency

### 4. **Environment Variable Proliferation**
Multiple environment variables control build behavior:
- Creates configuration complexity
- Breaks declarative configuration model  
- **Solution:** Single configuration source (TOML files)

## PROPOSED RESOLUTION STRATEGY

### Phase 1: Break Circular Dependencies
1. Extract tools functionality into zero-dependency trait crates
2. Implement trait-based dependency injection for build concerns  
3. Remove cross-crate build script dependencies

### Phase 2: Eliminate Build-time Generation
1. Replace generated code with runtime configuration loading
2. Move from build.rs to runtime initialization
3. Use TOML configuration files instead of generated Rust code

### Phase 3: Unify Client/SSR Architecture  
1. Create unified components that work in both environments
2. Implement safe reactive patterns without reactive_graph panics
3. Handle hydration mismatches at the framework level

### Phase 4: Pure Configuration-Driven Design
1. Replace all environment variables with TOML configuration
2. Implement configuration discovery and validation
3. Remove hardcoded paths and values

This analysis reveals the core architectural problems that prevent true PAP compliance and unified Client/SSR components.