# Project Structure

This document describes the organization of the Proxmox workspace project.

## Directory Structure

```
proxmox/
├── scripts/                    # Project root utility scripts
│   ├── README.md              # Scripts documentation
│   ├── setup.sh               # Initial setup script
│   ├── complete-setup.sh      # Complete setup script
│   ├── verify-setup.sh        # Setup verification
│   ├── configure-env.sh       # Environment configuration
│   ├── load-env.sh            # Standardized .env loader
│   ├── create-proxmox-token.sh # Token creation
│   ├── update-token.sh        # Token update
│   ├── test-connection.sh     # Connection testing
│   └── validate-ml110-deployment.sh # Deployment validation
│
├── docs/                       # Project documentation
│   ├── README.md              # Documentation index
│   ├── README_START_HERE.md   # Getting started guide
│   ├── PREREQUISITES.md        # Prerequisites
│   ├── MCP_SETUP.md            # MCP Server setup
│   ├── ENV_STANDARDIZATION.md  # Environment variables
│   ├── SETUP_STATUS.md         # Setup status
│   ├── SETUP_COMPLETE.md       # Setup completion
│   ├── CREDENTIALS_CONFIGURED.md # Credentials guide
│   ├── DEPLOYMENT_VALIDATION_REPORT.md # Deployment validation
│   └── ...                     # Additional documentation
│
├── mcp-proxmox/                # MCP Server submodule
│   ├── index.js                # Main server file
│   └── README.md               # MCP Server documentation
│
├── ProxmoxVE/                  # ProxmoxVE Helper Scripts submodule
│   ├── frontend/               # Next.js frontend
│   ├── install/                # Installation scripts
│   ├── tools/                  # Utility tools
│   └── docs/                   # ProxmoxVE documentation
│
├── smom-dbis-138-proxmox/      # Deployment scripts submodule
│   ├── scripts/                # Deployment scripts
│   ├── config/                 # Configuration files
│   ├── install/                # Installation scripts
│   └── docs/                   # Deployment documentation
│
├── README.md                    # Main project README
├── package.json                 # pnpm workspace configuration
├── pnpm-workspace.yaml          # Workspace definition
└── claude_desktop_config.json.example # Claude Desktop config template
```

## File Organization Principles

### Root Directory
The root directory contains only essential files:
- **README.md** - Main project documentation
- **package.json** - Package configuration
- **pnpm-workspace.yaml** - Workspace configuration
- **claude_desktop_config.json.example** - Configuration template

### scripts/ Directory
All project root utility scripts are organized here:
- Setup and configuration scripts
- Environment management scripts
- Testing and validation scripts
- Token management scripts

### docs/ Directory
All project documentation (except essential README files):
- Setup guides
- Configuration guides
- Quick references
- Deployment documentation
- Technical documentation

### Submodules
Each submodule maintains its own structure:
- **mcp-proxmox/** - MCP Server implementation
- **ProxmoxVE/** - Helper scripts and frontend
- **smom-dbis-138-proxmox/** - Deployment automation

## Environment Configuration

All scripts use a standardized `.env` file location: `~/.env`

See [docs/ENV_STANDARDIZATION.md](docs/04-configuration/ENV_STANDARDIZATION.md) for details.

## Script Usage

All scripts in the `scripts/` directory should be referenced with the `scripts/` prefix:

```bash
# Correct
./scripts/setup.sh
./scripts/verify-setup.sh

# Incorrect (old location)
./setup.sh
./verify-setup.sh
```

## Documentation References

Documentation files should reference other docs with the `docs/` prefix:

```markdown
# Correct
See [docs/MCP_SETUP.md](docs/04-configuration/MCP_SETUP.md)

# Incorrect (old location)
See [MCP_SETUP.md](docs/04-configuration/MCP_SETUP.md)
```

## Benefits of This Structure

1. **Clean Root Directory** - Only essential files in root
2. **Organized Scripts** - All utility scripts in one place
3. **Centralized Documentation** - Easy to find and maintain
4. **Clear Separation** - Scripts, docs, and submodules are clearly separated
5. **Easy Navigation** - Predictable file locations