Overview

Relevant source files

• LICENSE
• README.md

Purpose and Scope

This document introduces XaresAICoder, its purpose as a browser-based AI-powered development environment, and the high-level capabilities of the system. It provides a technical overview of the major components and their roles in delivering isolated development workspaces with integrated AI coding tools.

For detailed information on specific subsystems, see:

• System architecture details: System Architecture
• Frontend implementation: Frontend System
• Backend services: Backend Services
• Workspace container details: Workspace Containers
• Deployment procedures: Deployment & Infrastructure

Sources: README.md1-14

What is XaresAICoder?

XaresAICoder is a self-hosted platform that provides isolated VS Code development environments running in web browsers. Each workspace executes inside a dedicated Docker container running code-server, providing developers with full-featured IDE access through HTTP/HTTPS without requiring local IDE installation.

The system integrates multiple AI coding assistants (Continue, Cline, Aider, Gemini CLI, Claude Code, Qwen Code, OpenCode SST) pre-configured within each workspace, enabling AI-powered code completion, chat-based assistance, and automated file editing capabilities.

Sources: README.md1-14 README.md29-38

Core Capabilities

Workspace Management

The platform manages the complete lifecycle of development workspaces through these capabilities:

Capability	Implementation	Configuration
Isolated Containers	Each workspace runs in separate Docker container with code-server:8082	docker-compose.yml DockerService
Resource Allocation	Configurable CPU cores (1-8) and memory (1GB-16GB) per workspace	CPU_PER_WORKSPACE, MEMORY_PER_WORKSPACE_MB
Concurrent Limits	Maximum simultaneous running workspaces enforced	MAX_CONCURRENT_WORKSPACES
Port Forwarding	Subdomain-based routing (e.g., projectid-5000.localhost)	nginx.conf.template
Password Protection	Optional bcrypt-hashed password security	WorkspaceService
State Persistence	Project metadata stored in JSON file	/app/workspaces/projects.json

Sources: README.md18-27 README.md236-309

Project Organization

Projects can be organized into custom groups with drag-and-drop functionality:

• Groups stored in /app/workspaces/groups.json
• Default "Uncategorized" group for new projects
• Sidebar navigation for filtering projects by group
• RESTful API endpoints: /api/groups/, /api/groups/create, /api/groups/rename, /api/groups/delete

Sources: README.md49-66 README.md138-156

Git Integration

Diagram: Git Integration Architecture and Code Components

The system supports three Git integration modes:

1. Repository Cloning: HTTP/HTTPS Git URLs cloned directly into workspaces with persistent credentials
2. Private Authentication: Username and access token embedded in Git remote URLs for seamless push/pull
3. Integrated Git Server: Optional Forgejo instance for self-hosted repositories

Sources: README.md41-47 README.md67-73 README.md125-136 README.md310-327

System Components

Diagram: System Components with Code Entity Mapping

Component Descriptions

Frontend Components:

• XaresAICoder class in frontend/app.js manages application state, UI rendering, and API communication
• frontend/index.html defines the layout structure with activity bar, project list, and modal overlays
• frontend/style.css implements theming system with CSS variables for dark/light modes
• frontend/sw.js provides Progressive Web App offline caching capabilities

Backend Services:

• WorkspaceService class in server/workspaceService.js orchestrates workspace lifecycle and maintains the projects Map
• DockerService class in server/dockerService.js wraps Docker API for container operations
• GitService class in server/gitService.js interfaces with Forgejo API for Git repository management
• server/server.js instantiates Express application and mounts API route handlers

API Routes:

• server/routes/projects.js handles /api/projects/* endpoints for workspace CRUD operations
• server/routes/groups.js handles /api/groups/* endpoints for project organization
• server/routes/notes.js handles /api/notes/* endpoints for project metadata storage

Infrastructure:

• build/nginx.conf.template defines reverse proxy rules for static files, API proxying, and subdomain routing
• xares-aicoder-network Docker bridge network enables container communication
• /var/run/docker.sock socket mount enables Docker API access from backend container

Runtime Environment:

• xares-aicoder-codeserver:latest custom image based on codercom/code-server:latest
• docker-image/entrypoint.sh manages container startup sequence
• docker-image/workspace-init.sh initializes workspace environment, Git configuration, and AI tools
• workspace_data volume persists user code, VS Code settings, and project metadata

Sources: README.md1-14 Diagram 1, Diagram 3, Diagram 4 from system diagrams

Deployment Architecture

Diagram: Deployment Architecture with Code Entity References

Deployment Process

The deploy.sh script orchestrates the deployment through five phases:

1. Image Building: build_code_server_image() function deploy.sh60-92 builds xares-aicoder-codeserver:latest from docker-image/Dockerfile

2. Environment Setup: setup_environment() function deploy.sh94-139 generates .env from .env.example with user-provided or default values

3. Network Creation: setup_network() function deploy.sh141-155 ensures xares-aicoder-network exists

4. Service Deployment: deploy_application() function deploy.sh157-185 executes docker compose up -d using docker-compose.yml

5. Optional Git Server: When --git-server flag is provided, Forgejo service is started via git-server profile

Configuration Flow

Environment variables from .env propagate to all services:

Variable	Purpose	Default	Used By
BASE_DOMAIN	Domain for subdomain routing	localhost	nginx, server
BASE_PORT	External port for web interface	80	nginx
MAX_CONCURRENT_WORKSPACES	Concurrent workspace limit	3	WorkspaceService
CPU_PER_WORKSPACE	CPU cores per workspace	1.0	DockerService
MEMORY_PER_WORKSPACE_MB	Memory limit per workspace	4096	DockerService
ENABLE_GIT_SERVER	Enable Forgejo git-server profile	false	docker-compose
ENABLE_GPU	GPU passthrough to containers	false	DockerService

Sources: README.md80-104 README.md186-200 README.md236-309 deploy.sh .env.example docker-compose.yml

Key Technical Features

Container Isolation and Resource Limits

Each workspace container is created with specific Docker configuration enforced by DockerService:

Diagram: Container Security Configuration

Resource limits are enforced through Docker's cgroup controls:

• Memory: HostConfig.Memory set to MEMORY_PER_WORKSPACE_MB * 1024 * 1024 bytes
• CPU: HostConfig.NanoCpus set to CPU_PER_WORKSPACE * 1e9 nanocpus
• Process limit: HostConfig.PidsLimit prevents fork bombs
• Capabilities: All Linux capabilities dropped except essential ones for VS Code operation

Sources: README.md18-27 README.md229-234 README.md236-309 Diagram 3 from system diagrams

Progressive Web App Support

The frontend implements PWA capabilities for offline access:

• frontend/manifest.json defines app metadata, icons, and display mode
• frontend/sw.js service worker caches static assets and API responses
• Install prompt functionality in XaresAICoder class enables home screen installation
• Offline detection and graceful degradation in API communication layer

Sources: README.md1-14 frontend/manifest.json frontend/sw.js Diagram 4 from system diagrams

AI Tools Integration

Pre-installed AI coding assistants within each workspace container:

Tool	Type	Installation Location	Setup Command
Continue	VS Code Extension	.local/share/code-server/extensions/	Pre-installed
Cline	VS Code Extension	.local/share/code-server/extensions/	Pre-installed
Aider	CLI Tool	/usr/local/bin/aider	pip install aider-chat
Gemini CLI	CLI Tool	/usr/local/bin/gemini	Via npm global
Claude Code	CLI Tool	/usr/local/bin/claude-code	Via npm global
Qwen Code	CLI Tool	/usr/local/bin/qwen	Via pip
OpenCode SST	VS Code Extension	.local/share/code-server/extensions/	Pre-installed

The docker-image/workspace-init.sh script initializes tool configurations and the setup_ai_tools command provides detailed setup instructions within workspaces.

Sources: README.md29-39 README.md164-171 docker-image/Dockerfile docker-image/workspace-init.sh

Project Templates

Four project templates are available during workspace creation:

1. Empty Project: Git initialization with README
2. Python Flask: Flask application with virtual environment and dependencies
3. Node.js React: React 18 + Vite with modern JavaScript tooling
4. Java Spring Boot: Spring Boot 3.1 with Maven configuration

Template initialization occurs in docker-image/workspace-init.sh based on the PROJECT_TYPE environment variable passed during container creation.

Sources: README.md111-124 docker-image/workspace-init.sh

Subdomain-Based Port Forwarding

Nginx reverse proxy configuration in build/nginx.conf.template implements dynamic subdomain routing:

• Pattern: {projectId}-{port}.{BASE_DOMAIN}
• Example: abc123-5000.localhost routes to container xares-workspace-abc123 port 5000
• Regex-based location matching extracts project ID and port from subdomain
• Dynamic upstream resolution using proxy_pass to container network

This enables VS Code's port forwarding feature to automatically generate accessible URLs for development servers running inside containers.

Sources: README.md218-227 build/nginx.conf.template Diagram 1 from system diagrams

---

This overview provides the foundational understanding of XaresAICoder's architecture and capabilities. For detailed information on specific subsystems, refer to the linked wiki pages throughout this document.