soleprint/mainroom/sbwrapper

Soleprint Wrapper - Development Tools Sidebar

A collapsible sidebar that provides development and testing tools for any soleprint-managed room (like amar) without interfering with the managed application.

Features

👤 Quick Login

• Switch between test users with one click
• Pre-configured admin, vet, and tutor accounts
• Automatic JWT token management
• Shows currently logged-in user

🌍 Environment Info

• Display backend and frontend URLs
• Room name and deployment info
• Quick reference during development

⌨️ Keyboard Shortcuts

• Ctrl+Shift+P - Toggle sidebar

💾 State Persistence

• Sidebar remembers expanded/collapsed state
• Persists across page reloads

Files

wrapper/
├── index.html          # Standalone demo
├── sidebar.css         # Sidebar styling
├── sidebar.js          # Sidebar logic
├── config.json         # Configuration (users, URLs)
└── README.md           # This file

Quick Start

Standalone Demo

Open index.html in your browser to see the sidebar in action:

cd core_room/wrapper
python3 -m http.server 8080
# Open http://localhost:8080

Click the toggle button on the right edge or press Ctrl+Shift+P.

Integration with Your App

Add these two lines to your HTML:

<link rel="stylesheet" href="/wrapper/sidebar.css">
<script src="/wrapper/sidebar.js"></script>

The sidebar will automatically:

1. Load configuration from /wrapper/config.json
2. Create the sidebar UI
3. Setup keyboard shortcuts
4. Check for existing logged-in users

Configuration

Edit config.json to customize:

{
  "room_name": "amar",
  "wrapper": {
    "enabled": true,
    "environment": {
      "backend_url": "http://localhost:8000",
      "frontend_url": "http://localhost:3000"
    },
    "users": [
      {
        "id": "admin",
        "label": "Admin",
        "username": "admin@test.com",
        "password": "Amar2025!",
        "icon": "👑",
        "role": "ADMIN"
      }
    ]
  }
}

User Fields

• id: Unique identifier for the user
• label: Display name in the sidebar
• username: Login username (email)
• password: Login password
• icon: Emoji icon to display
• role: User role (ADMIN, VET, USER)

How It Works

Login Flow

1. User clicks a user card in the sidebar
2. sidebar.js calls POST {backend_url}/api/token/ with credentials
3. Backend returns JWT tokens: { access, refresh, details }
4. Tokens stored in localStorage
5. Page reloads, user is now logged in

Token Storage

Tokens are stored in localStorage:

• access_token - JWT access token
• refresh_token - JWT refresh token
• user_info - User metadata (username, label, role)

Logout Flow

1. User clicks "Logout" button
2. Tokens removed from localStorage
3. Page reloads, user is logged out

Docker Integration

Approach 1: Static Files

Mount wrapper as static files in docker-compose:

services:
  frontend:
    volumes:
      - ./ctrl/wrapper:/app/public/wrapper:ro

Then in your HTML:

<link rel="stylesheet" href="/wrapper/sidebar.css">
<script src="/wrapper/sidebar.js"></script>

Approach 2: Nginx Injection

Use nginx to inject the sidebar script automatically:

location / {
    sub_filter '</head>' '<link rel="stylesheet" href="/wrapper/sidebar.css"><script src="/wrapper/sidebar.js"></script></head>';
    sub_filter_once on;
    proxy_pass http://frontend:3000;
}

location /wrapper/ {
    alias /app/wrapper/;
}

Approach 3: Wrapper Service

Create a dedicated wrapper service:

services:
  wrapper:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./ctrl/wrapper:/usr/share/nginx/html/wrapper
    environment:
      - MANAGED_APP_URL=http://frontend:3000

See ../WRAPPER_DESIGN.md for detailed Docker integration patterns.

Customization

Styling

Edit sidebar.css to customize appearance:

:root {
  --sidebar-width: 320px;
  --sidebar-bg: #1e1e1e;
  --sidebar-text: #e0e0e0;
  --sidebar-accent: #007acc;
}

Add New Panels

Add HTML to getSidebarHTML() in sidebar.js:

getSidebarHTML() {
  return `
    ...existing panels...

    <div class="panel">
      <h3>🆕 My New Panel</h3>
      <p>Custom content here</p>
    </div>
  `;
}

Add New Features

Extend the SoleprintSidebar class in sidebar.js:

class SoleprintSidebar {
  async fetchJiraInfo() {
    const response = await fetch('https://artery.mcrn.ar/jira/VET-123');
    const data = await response.json();
    // Update UI with data
  }
}

API Requirements

The sidebar expects these endpoints from your backend:

POST /api/token/

Login endpoint that returns JWT tokens.

Request:

{
  "username": "admin@test.com",
  "password": "Amar2025!"
}

Response:

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "details": {
    "role": "ADMIN",
    "id": 1,
    "name": "Admin User"
  }
}

Troubleshooting

Sidebar not appearing

• Check browser console for errors
• Verify sidebar.js and sidebar.css are loaded
• Check that config.json is accessible

Login fails

• Verify backend URL in config.json
• Check backend is running
• Verify credentials are correct
• Check CORS settings on backend

Tokens not persisting

• Check localStorage is enabled
• Verify domain matches between sidebar and app
• Check browser privacy settings

Security Considerations

⚠️ Important: This sidebar is for development/testing only.

• Passwords are stored in plain text in config.json
• Do NOT use in production
• Do NOT commit real credentials to git
• Add config.json to .gitignore if it contains sensitive data

For production:

• Disable wrapper via "enabled": false in config
• Use environment variables for URLs
• Remove or secure test user credentials

Future Enhancements

Planned features (see ../WRAPPER_DESIGN.md):

• 📋 Jira Info Panel - Fetch ticket details from artery
• 📊 Logs Viewer - Stream container logs
• 🎨 Theme Switcher - Light/dark mode
• 🔍 Search - Quick search across tools
• ⚙️ Settings - Customize sidebar behavior
• 📱 Mobile Support - Responsive design improvements

Related Documentation

• ../WRAPPER_DESIGN.md - Complete architecture design
• ../../../soleprint/CLAUDE.md - Soleprint framework overview
• ../../README.md - Core room documentation

Contributing

To add a new panel or feature:

1. Add HTML in getSidebarHTML()
2. Add styling in sidebar.css
3. Add logic as methods on SoleprintSidebar class
4. Update this README with usage instructions

License

Part of the Soleprint development tools ecosystem.