proxmox/PROJECT_STRUCTURE.md

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
│   ├── MASTER_INDEX.md         # Master documentation index (start here)
│   ├── README.md               # Documentation overview
│   ├── 01-getting-started/     # Getting started
│   │   ├── README.md
│   │   ├── README_START_HERE.md
│   │   └── PREREQUISITES.md
│   ├── 04-configuration/       # Configuration & setup
│   │   ├── MCP_SETUP.md         # MCP Server setup
│   │   ├── ENV_STANDARDIZATION.md # Environment variables
│   │   ├── CREDENTIALS_CONFIGURED.md # Credentials guide
│   │   └── ...
│   ├── 02-architecture/         # Architecture & deployment
│   ├── 03-deployment/           # Operations & runbooks
│   ├── 05-network/             # Network infrastructure
│   └── ...                     # 06-besu through 12-quick-reference, 00-meta, archive
│
├── 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:

• lib/load-project-env.sh — Shared env loader (.env, config, smom-dbis-138); use instead of hardcoding IPs
• bridge/ — CCIP bridge scripts (e.g. run-send-cross-chain.sh)
• dbis/ — DBIS Core deployment (e.g. deploy-dbis-frontend-to-container.sh)
• verify/ — Verification scripts (e.g. run-contract-verification-with-proxy.sh)
• 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/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