# 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](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