Atomizer/docs/hq/PROJECT_STRUCTURE.md

# Standard Project Structure

**Version**: 1.0  
**Created**: February 2026  
**Reference Implementation**: `projects/hydrotech-beam/`

---

## Overview

All Atomizer-HQ projects follow a standardized Knowledge Base-integrated structure. This ensures consistent organization, efficient handoffs between agents, and proper accumulation of domain knowledge.

**Key Principles**:
- **Single Source of Truth** — Each project has one authoritative structure
- **KB Integration** — Knowledge accumulates in structured format
- **Study-Project Separation** — Studies are execution units, projects are business units
- **Reference → Copy Flow** — Models flow from reference to study-specific copies

---

## Full Project Directory Structure

```
projects/[project-name]/
│
├── README.md                          # Project overview, status, contacts
├── project_metadata.json              # Structured project info
│
├── deliverables/                      # Client-facing outputs
│   ├── reports/                       # Technical reports, presentations
│   ├── models/                        # Final optimized models
│   └── data/                          # Results datasets, exports
│
├── images/                            # Visual assets (organized by type)
│   ├── components/                    # Part/assembly images
│   ├── studies/                       # Study result visualizations
│   ├── analysis/                      # Analysis plots, graphs
│   └── deliverables/                  # Client presentation images
│
├── kb/                                # Knowledge Base (THE CORE)
│   ├── README.md                      # KB navigation and conventions
│   ├── components/                    # Component-specific knowledge
│   │   ├── [component-name].md        # Per-component accumulation
│   │   └── manufacturing-constraints.md
│   ├── materials/                     # Material property knowledge
│   │   ├── steel-properties.md
│   │   └── material-selection-criteria.md
│   ├── fea/                          # FEA-specific knowledge
│   │   ├── models/                    # Model setup knowledge
│   │   │   ├── meshing-conventions.md
│   │   │   ├── boundary-conditions.md
│   │   │   └── modeling-assumptions.md
│   │   ├── load-cases/                # Load case documentation
│   │   │   ├── operational-loads.md
│   │   │   └── safety-factors.md
│   │   └── results/                   # Results interpretation
│   │       ├── stress-criteria.md
│   │       └── failure-modes.md
│   ├── dev/                          # Development knowledge
│   │   ├── lessons-learned.md         # Project-specific lessons
│   │   ├── optimization-insights.md   # What worked, what didn't
│   │   └── process-improvements.md    # Workflow refinements
│   └── client/                       # Client-specific knowledge (optional)
│       ├── requirements.md            # Client requirements evolution
│       └── preferences.md             # Client preferences and constraints
│
├── models/                           # Reference models (READ-ONLY for studies)
│   ├── reference/                    # Original/baseline models
│   │   ├── [component].prt           # CAD models
│   │   ├── [component].sim           # NX simulation setups
│   │   └── [component].fem           # FEM files
│   ├── variations/                   # Design variations
│   └── optimized/                    # Final optimized models
│
└── studies/                          # Links to actual studies directory
    ├── 01_baseline_validation/       # → ../../../studies/project_01_baseline/
    ├── 02_stress_optimization/       # → ../../../studies/project_02_stress/
    └── README.md                     # Study execution log
```

---

## Directory Responsibilities

### Core Directories

| Directory | Owner | Purpose | Frequency |
|-----------|-------|---------|-----------|
| `README.md` | Manager | Project status, contacts | Updated weekly |
| `project_metadata.json` | Secretary | Structured project data | Updated on changes |
| `deliverables/` | Reporter | Client-facing outputs | End of phases |
| `kb/` | **Everyone** | Accumulated knowledge | **Continuous** |
| `models/reference/` | Technical Lead | Baseline models | Setup phase |
| `studies/` | Optimizer | Study execution links | Per study |

### KB Subdirectories

| KB Directory | Primary Owner | Content |
|--------------|---------------|---------|
| `components/` | Technical Lead | Component behavior, constraints |
| `materials/` | Technical Lead | Material properties, selection |
| `fea/models/` | Technical Lead | Modeling conventions, assumptions |
| `fea/load-cases/` | Technical Lead | Load cases, boundary conditions |
| `fea/results/` | Post-Processor | Results interpretation, criteria |
| `dev/` | All Agents | Process lessons, optimization insights |

---

## File Naming Conventions

### General Rules
- **Lowercase with hyphens**: `component-analysis.md`, not `Component_Analysis.md`
- **Descriptive names**: `steel-yield-strength.md`, not `steel.md`
- **No spaces**: Use hyphens, not spaces
- **Consistent extensions**: `.md` for documentation, `.json` for data

### Specific Conventions

**Components**: `[component-type]-[specific-name].md`
```
beam-support-bracket.md
hydraulic-cylinder-mount.md
```

**Materials**: `[material-type]-[property].md`
```
steel-properties.md
aluminum-6061-characteristics.md
```

**Studies**: `[number]_[descriptive-name]`
```
01_baseline_validation
02_stress_minimization
03_mass_reduction_study
```

---

## Model Flow Conventions

### Reference → Study Copy Pattern

1. **Reference Models** (`models/reference/`)
   - Original/baseline models
   - **READ-ONLY** for studies
   - Version controlled
   - Maintained by Technical Lead

2. **Study Copies** (`studies/[study-name]/model/`)
   - **Copied from reference** at study creation
   - Modified during optimization
   - Study-specific versions
   - Managed by Optimizer

3. **Optimized Models** (`models/optimized/`)
   - Best results from studies
   - **Copied from study results**
   - Final deliverable candidates
   - Curated by Technical Lead

### Model Versioning
```
models/reference/bracket-v1.0.prt          # Initial design
models/reference/bracket-v1.1.prt          # Design revision
studies/stress-opt/model/bracket.prt       # Study working copy
models/optimized/bracket-optimized-v2.0.prt # Final optimized
```

---

## Project Creation Workflow

### 1. Secretary: Project Intake
```bash
# Create project directory
mkdir -p projects/[project-name]/{deliverables,images,kb,models,studies}

# Create metadata
# (See project_metadata.json template)
```

### 2. Manager: Structure Setup
```bash
# Copy template structure
cp -r templates/project-template/* projects/[project-name]/

# Create README from template
# Update with project specifics
```

### 3. Technical Lead: KB Initialization
```bash
# Create component files
touch projects/[project-name]/kb/components/[component].md

# Initialize FEA knowledge structure
mkdir -p projects/[project-name]/kb/fea/{models,load-cases,results}

# Create reference models directory
mkdir -p projects/[project-name]/models/reference
```

---

## Study Integration

### Study-Project Relationship
- **Projects** = Business/client organizing unit
- **Studies** = Technical execution unit
- Studies reference project KB and models
- Results flow back to project KB

### Creating Project Studies
```bash
# Create study linked to project
mkdir studies/project_01_baseline
ln -s ../../../projects/[project]/studies studies/project_01_baseline/project_link

# Copy reference models to study
cp projects/[project]/models/reference/* studies/project_01_baseline/model/

# Study inherits project KB context
```

### Results Flow Back
1. **Study completes** → Results in `studies/[study]/results/`
2. **Post-Processor analyzes** → Insights documented
3. **KB accumulation** → Knowledge flows to `projects/[project]/kb/`
4. **Model archival** → Best models to `projects/[project]/models/optimized/`

---

## KB Accumulation Principles

### The Golden Rule: Add, Never Replace
- **DO**: Append new insights, learnings, results
- **DO NOT**: Overwrite existing knowledge
- **Timestamp entries**: Generation tracking for all additions
- **Version knowledge**: Track what was learned when

### Component Knowledge Evolution
```markdown
# beam-support-analysis.md

## Generation 1: Initial Analysis (2026-02-01)
- Material: Steel A36
- Critical stress location: Root of bracket
- Baseline performance: 180 MPa max stress

## Generation 2: First Optimization (2026-02-05) 
- Discovered: Fillet radius critical to stress concentration
- Optimized radius from 5mm → 8mm reduced stress by 15%
- New critical location: Mounting bolt interface

## Generation 3: Load Case Refinement (2026-02-08)
- Added dynamic loading consideration
- Peak stress now 220 MPa under dynamic conditions
- Recommendation: Consider fatigue analysis
```

---

## Templates

### project_metadata.json Template
```json
{
  "project_name": "project-name",
  "client": "Client Name",
  "project_manager": "agent-name",
  "technical_lead": "agent-name",
  "created": "2026-02-01",
  "status": "active",
  "phase": "introspection",
  "description": "Brief project description",
  "components": ["component1", "component2"],
  "objectives": ["minimize stress", "reduce mass"],
  "constraints": ["manufacturing feasibility"],
  "studies": [
    {
      "name": "01_baseline_validation",
      "status": "completed",
      "study_link": "../../../studies/project_01_baseline"
    }
  ],
  "deliverables": {
    "interim_report": "deliverables/reports/interim-report.pdf",
    "final_report": "deliverables/reports/final-report.pdf",
    "optimized_models": "models/optimized/"
  }
}
```

### Project README Template
```markdown
# [Project Name]

**Client**: [Client Name]  
**Status**: [Active/Completed/On Hold]  
**Phase**: [Intake/Breakdown/Introspection/Study/Results/Deliverables]  
**Manager**: [Agent Name]  
**Technical Lead**: [Agent Name]  

## Objective
[Brief description of what we're optimizing]

## Components
- [Component 1] — [Brief description]
- [Component 2] — [Brief description]

## Current Status
[What's happening now, next steps]

## Studies
- [Study 1] — [Status] — [Brief outcome]
- [Study 2] — [Status] — [Brief outcome]

## Key Findings
[Major insights, recommendations]

## Deliverables
- [X] Baseline analysis
- [ ] Optimization study
- [ ] Final report
```

---

## Best Practices

### Project Organization
1. **One project per client deliverable**
2. **Clear phase progression** (don't skip phases)
3. **Regular KB updates** (not just at end)
4. **Study naming consistency** (01_, 02_, etc.)

### Knowledge Base Maintenance
1. **Write as you work** — Don't accumulate at the end
2. **Be specific** — "Fillet radius affects stress concentration" not "Design matters"
3. **Include context** — Why was this learned? What led to this insight?
4. **Link studies** — Reference which study generated the knowledge

### Model Management
1. **Protect reference models** — No direct modification
2. **Study isolation** — Each study gets its own model copies
3. **Version final models** — Clear naming for optimized versions
4. **Archive intermediate** — Keep best intermediate results

---

## Living Example: Hydrotech Beam Project

**Reference**: `projects/hydrotech-beam/`

This project demonstrates the full structure in practice:
- Complete KB with component, material, and FEA knowledge
- Multiple studies linked and executed
- Results flowing back to project KB
- Deliverables organized for client handoff

**Key Learnings from Hydrotech**:
- KB accumulation prevented re-discovering constraints
- Study-project linking maintained context
- Reference model protection avoided corruption
- Generation tracking showed knowledge evolution

---

## Questions and Updates

- **Structure Questions**: Ask Manager or Technical Lead
- **KB Conventions**: See `KB_CONVENTIONS.md`
- **Study Execution**: See `STUDY_CONVENTIONS.md`
- **Process Issues**: Document in project `kb/dev/lessons-learned.md`

Last updated: February 2026