ASF_tools/asf-cloud-server/TBM_devbench/docs/STRUCTURE.md

# DevBench Manager - Project Structure

## Directory Tree

```
ASF_devbench/
├── docs/                           # Documentation
│   ├── ARCHITECTURE.md            # System architecture
│   ├── STRUCTURE.md               # This file
│   ├── DEPLOYMENT.md              # Deployment guide
│   └── API.md                     # API documentation
│
├── public/                         # Static assets
│   ├── css/
│   │   └── style.css              # Custom styles + dark theme
│   ├── images/
│   │   ├── nabd-logo.svg          # Company logo (light)
│   │   ├── nabd-logo-white.svg    # Company logo (dark)
│   │   └── tbm-icon.png           # TBM branding icon
│   └── downloads/
│       └── db_vm_ssh_config_manager.exe  # SSH config tool
│
├── views/                          # EJS templates
│   ├── layout.ejs                 # Base layout with navbar
│   ├── login.ejs                  # Login page
│   ├── dashboard.ejs              # User dashboard
│   ├── admin.ejs                  # Admin panel
│   └── help.ejs                   # Help/documentation page
│
├── data/                           # Database storage (created on deploy)
│   └── devbench.db                # SQLite database
│
├── logs/                           # Application logs (created on deploy)
│   └── *.log                      # Log files
│
├── server.js                       # Main application server
├── config.js                       # Configuration settings
├── package.json                    # Node.js dependencies
├── provision_vm.sh                 # VM provisioning script
│
├── Dockerfile                      # Docker image definition
├── docker-compose.yml              # Container orchestration
├── .dockerignore                   # Docker build exclusions
│
├── deploy.sh                       # Deployment script
├── install.sh                      # Local installation script
├── start.sh                        # Start script (Docker/Node)
├── cleanup.sh                      # Cleanup script
│
├── .env.example                    # Environment variables template
├── .gitignore                      # Git exclusions
├── README.md                       # Main documentation
└── CHANGELOG.md                    # Change history
```

## File Descriptions

### Core Application Files

#### `server.js`
**Purpose**: Main Express.js application server

**Key Components**:
- Express app initialization
- Database setup and schema
- Route definitions
- WebSocket server
- Authentication middleware
- DevBench management logic
- Provision script executor
- Status monitoring (60-second interval)

**Dependencies**:
- express
- express-session
- sqlite3
- bcryptjs
- ws (WebSocket)
- child_process (for script execution)

**Key Functions**:
```javascript
- requireAuth()           // Authentication middleware
- requireAdmin()          // Admin authorization middleware
- executeProvisionScript() // Execute VM provisioning
- broadcastToUser()       // WebSocket messaging
```

#### `config.js`
**Purpose**: Centralized configuration

**Settings**:
- Server port
- Database path
- Session configuration
- Default admin credentials
- Validation patterns
- Provision script settings

#### `provision_vm.sh`
**Purpose**: VM provisioning and management

**Commands**:
- `create <vm_name>`: Create new VM
- `status <vm_name>`: Check VM status
- `delete <vm_name>`: Delete VM
- `activate <vm_name>`: Activate VM
- `start <vm_name>`: Start VM
- `stop <vm_name>`: Stop VM

**Features**:
- SSH connection to remote host
- Output logging
- Connection info extraction
- Error handling
- Timeout management (30 minutes)

### Frontend Files

#### `views/layout.ejs`
**Purpose**: Base template for all pages

**Features**:
- Navigation bar with logo
- Help link
- Theme toggle button
- WebSocket initialization
- Bootstrap and Font Awesome imports
- Dark theme JavaScript

#### `views/dashboard.ejs`
**Purpose**: User dashboard

**Features**:
- DevBench list with cards
- Create DevBench modal
- Connection info display (SSH/VNC ports)
- Real-time log output
- Status indicators
- Copy-to-clipboard functionality

#### `views/admin.ejs`
**Purpose**: Admin panel

**Features**:
- User management table
- Add user modal
- DevBench overview table
- Password reset
- User deletion
- DevBench deletion

#### `views/help.ejs`
**Purpose**: Help and documentation

**Features**:
- SSH Config Manager guide
- Step-by-step instructions
- Download link for tool
- Connection information
- Important notes

#### `views/login.ejs`
**Purpose**: Authentication page

**Features**:
- Login form
- Error messages
- Branding

### Static Assets

#### `public/css/style.css`
**Purpose**: Custom styling

**Features**:
- NABD brand colors
- Dark theme styles
- Component styling
- Responsive design
- Smooth transitions

#### `public/images/`
**Purpose**: Image assets

**Files**:
- `nabd-logo.svg`: Light theme logo
- `nabd-logo-white.svg`: Dark theme logo
- `tbm-icon.png`: Branding icon and favicon

#### `public/downloads/`
**Purpose**: Downloadable files

**Files**:
- `db_vm_ssh_config_manager.exe`: SSH configuration tool

### Deployment Files

#### `Dockerfile`
**Purpose**: Docker image definition

**Base Image**: node:18-alpine

**Steps**:
1. Set working directory
2. Copy package files
3. Install dependencies
4. Copy application files
5. Create data/logs directories
6. Expose port 3001
7. Set start command

#### `docker-compose.yml`
**Purpose**: Container orchestration

**Configuration**:
- Service: devbench-manager
- Port mapping: 9090:3001
- Volumes: data, logs, provision script
- Networks: app-network, caddy_network
- Health check: /health endpoint
- Restart policy: unless-stopped

#### `deploy.sh`
**Purpose**: Automated deployment

**Steps**:
1. Create directories
2. Set permissions
3. Clean up old containers
4. Create Docker network
5. Build and start container
6. Wait for startup
7. Verify health
8. Display access information

### Configuration Files

#### `package.json`
**Purpose**: Node.js project configuration

**Scripts**:
- `start`: Run production server
- `dev`: Run with nodemon (auto-reload)

**Dependencies**:
- express: Web framework
- express-session: Session management
- bcryptjs: Password hashing
- sqlite3: Database
- body-parser: Request parsing
- ejs: Template engine
- ws: WebSocket
- child_process: Script execution

#### `.env.example`
**Purpose**: Environment variables template

**Variables**:
- NODE_ENV
- PORT
- SECRET_KEY
- ADMIN_EMAIL
- ADMIN_PASSWORD

#### `.gitignore`
**Purpose**: Git exclusions

**Excluded**:
- node_modules/
- data/
- logs/
- .env
- *.log
- .DS_Store

### Utility Scripts

#### `install.sh`
**Purpose**: Local installation

**Actions**:
- Check Node.js version
- Install npm dependencies
- Display start instructions

#### `start.sh`
**Purpose**: Start application

**Logic**:
- Check for Docker
- Start with Docker Compose if available
- Fall back to Node.js
- Install dependencies if needed

#### `cleanup.sh`
**Purpose**: Clean up containers

**Actions**:
- Stop containers
- Remove containers
- Prune dangling containers
- List volumes

### Documentation Files

#### `README.md`
**Purpose**: Main project documentation

**Sections**:
- Features overview
- Installation instructions
- Configuration guide
- Usage instructions
- API endpoints
- Troubleshooting

#### `CHANGELOG.md`
**Purpose**: Change history

**Content**:
- Recent updates
- SSH configuration changes
- Output format changes
- New features
- Migration notes

#### `docs/ARCHITECTURE.md`
**Purpose**: System architecture

**Content**:
- Architecture diagrams
- Component descriptions
- Data flow
- Security architecture
- Technology stack

#### `docs/DEPLOYMENT.md`
**Purpose**: Deployment guide

**Content**:
- Prerequisites
- Deployment steps
- Configuration
- Troubleshooting
- Maintenance

## Data Flow Through Files

### DevBench Creation
```
1. views/dashboard.ejs
   ↓ (User clicks Create)
2. server.js (POST /create-devbench)
   ↓ (Validates and creates DB record)
3. server.js (executeProvisionScript)
   ↓ (Spawns child process)
4. provision_vm.sh
   ↓ (SSH to remote host)
5. Remote VM Host
   ↓ (Creates VM, returns info)
6. provision_vm.sh
   ↓ (Parses output)
7. server.js
   ↓ (Updates database)
8. WebSocket
   ↓ (Broadcasts to user)
9. views/dashboard.ejs
   ↓ (Updates UI)
```

### Authentication
```
1. views/login.ejs
   ↓ (User submits form)
2. server.js (POST /login)
   ↓ (Validates credentials)
3. config.js (validation patterns)
   ↓
4. server.js (bcrypt compare)
   ↓ (Creates session)
5. express-session
   ↓ (Stores session)
6. server.js (redirect)
   ↓
7. views/dashboard.ejs or views/admin.ejs
```

### Theme Toggle
```
1. views/layout.ejs (Theme toggle button)
   ↓ (User clicks)
2. JavaScript (theme toggle handler)
   ↓ (Toggles class)
3. public/css/style.css (dark-theme styles)
   ↓ (Applies styles)
4. localStorage
   ↓ (Saves preference)
```

## Key Directories

### `/data`
- **Created**: On first deployment
- **Purpose**: SQLite database storage
- **Persistence**: Docker volume
- **Backup**: Copy devbench.db file

### `/logs`
- **Created**: On first deployment
- **Purpose**: Application logs
- **Persistence**: Docker volume
- **Rotation**: Manual

### `/public`
- **Purpose**: Static assets served by Express
- **Access**: Direct URL paths
- **Caching**: Browser caching enabled

### `/views`
- **Purpose**: EJS templates
- **Rendering**: Server-side
- **Access**: Via routes only

### `/docs`
- **Purpose**: Project documentation
- **Format**: Markdown
- **Access**: File system only

## Configuration Hierarchy

```
1. Environment Variables (.env)
   ↓
2. config.js (defaults)
   ↓
3. docker-compose.yml (container env)
   ↓
4. Application runtime
```

## Port Mapping

```
External → Container → Application
9090    → 3001      → Express Server
```

## Network Architecture

```
Internet
   ↓
Caddy (caddy_network)
   ↓
DevBench Manager (caddy_network + app-network)
   ↓
SQLite (local file)
   ↓
SSH (external)
   ↓
Remote VM Host
```

## File Permissions

### Scripts
- `provision_vm.sh`: 755 (executable)
- `deploy.sh`: 755 (executable)
- `install.sh`: 755 (executable)
- `start.sh`: 755 (executable)
- `cleanup.sh`: 755 (executable)

### Directories
- `data/`: 755
- `logs/`: 755
- `public/`: 755

### Database
- `devbench.db`: 644 (read/write for owner)

## Build Process

### Docker Build
```
1. Read Dockerfile
2. Pull node:18-alpine
3. Copy package.json
4. npm install
5. Copy application files
6. Set permissions
7. Create image
```

### Docker Compose
```
1. Read docker-compose.yml
2. Create networks
3. Build image (if needed)
4. Create container
5. Mount volumes
6. Start container
7. Run health checks
```

## Runtime Process

### Container Startup
```
1. Docker starts container
2. Node.js starts
3. server.js executes
4. Database initialized
5. Express server starts
6. WebSocket server starts
7. Health check passes
8. Ready for connections
```

### Request Handling
```
1. Request arrives at Caddy
2. Proxied to container
3. Express routes request
4. Middleware checks auth
5. Controller handles logic
6. Database query (if needed)
7. Template rendered
8. Response sent
```