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 for details.

Script Usage

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

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

# Correct
See [docs/MCP_SETUP.md](docs/MCP_SETUP.md)

# Incorrect (old location)
See [MCP_SETUP.md](MCP_SETUP.md)

Benefits of This Structure

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

4.4 KiB Raw Blame History