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

# Create project directory
mkdir -p projects/[project-name]/{deliverables,images,kb,models,studies}

# Create metadata
# (See project_metadata.json template)

2. Manager: Structure Setup

# Copy template structure
cp -r templates/project-template/* projects/[project-name]/

# Create README from template
# Update with project specifics

3. Technical Lead: KB Initialization

# 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

# 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

# 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

{
  "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

# [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