Outline VPN Manager Development Assistant

Expert assistant for the Outline VPN web management application - a full-stack TypeScript project integrating with Outline VPN servers for comprehensive access key, user, billing, and server administration.

Project Architecture

Backend (`/backend`)

Frontend (`/frontend`)

Key Backend Services

Key Frontend Pages

Critical Development Workflow

HIGHEST PRIORITY: Agent-Based Development

**ALL user requests MUST go through specialized agents - NEVER work directly**

1. **dev-team-coordinator** - ALWAYS USE FIRST for any user request

- Acts as team lead/manager for all development tasks

- Analyzes requirements and delegates to appropriate specialists

- Coordinates complex multi-step features and bug fixes

- Tracks project progress across all agents

2. **Specialized Agents** (delegated by coordinator):

- **frontend-feature-developer**: New UI features, components, pages

- **frontend-bug-fixer**: UI bugs, styling issues, component fixes

- **typescript-backend-developer**: New API endpoints, backend features

- **backend-bug-hunter**: Backend bugs, API issues, server problems

- **frontend-test-writer**: Frontend unit/integration tests

- **backend-test-writer**: Backend API/service tests

- **cicd-docker-engineer**: Docker, CI/CD, deployment configuration

3. **Mandatory Workflow**:

```

User Request → dev-team-coordinator → Specialist Agent(s) → Complete Task

```

**NEVER bypass this workflow - always start with dev-team-coordinator agent!**

Development Commands

Quick UI Development (Recommended)

```bash

Start development environment with hot reload

./dev.sh dev

This starts:

- Backend and database in Docker containers

- Frontend with Vite dev server (hot reload) in Docker

- Frontend: http://localhost:3000

- Backend API: http://localhost:3001/api

- Database: localhost:5433

Login credentials:

Admin: [email protected] / admin123

User: [email protected] / user123

```

**ALWAYS use `./dev.sh dev` for development workflow** - this enables hot reload for frontend changes. After making frontend changes, they will be automatically reflected at http://localhost:3000.

Production Testing

```bash

Full production build and test

./dev.sh test

Available at: http://localhost:8080

```

**NEVER use full production builds for UI testing** - use dev environment for quick iterations. Only use `./dev.sh test` when testing the full production build.

Manual Development

```bash

Backend development

cd backend

npm install

npm run dev

Frontend development

cd frontend

npm install

npm run dev

Database operations

npx prisma migrate dev

npx prisma db seed

npx prisma studio

```

Development Script Commands

```bash

./dev.sh build # Build images locally

./dev.sh up # Start local development environment

./dev.sh logs # Show logs (optionally specify service)

./dev.sh stop # Stop local environment

./dev.sh clean # Clean up all local data

./dev.sh seed # Seed database with test users

./dev.sh test # Test locally before deploying

./dev.sh deploy # Build and push to production registry

```

Deployment Workflows

Local to Registry Deployment

```bash

Build and push images to Docker registry

./dev.sh deploy

Uses docker-compose.registry.yml for registry configuration

```

Server Deployment (after registry push)

```bash

On production server

git pull origin master

docker compose -f docker-compose.server.yml pull

docker compose -f docker-compose.server.yml up -d --force-recreate

Or use deployment script

./deploy.sh

```

Manual Production Deployment

```bash

Configure environment

cp .env.production .env

Edit .env with production settings

Deploy

./deploy.sh

Or manual

docker-compose -f docker-compose.prod.yml up -d

```

Environment Configuration

Required environment variables in `.env`:

Key Dependencies

Backend

Frontend

Code Architecture Notes

Important Constraints

1. **Agent workflow is mandatory** - always start with dev-team-coordinator

2. **Use `./dev.sh dev` for all UI development** - hot reload enabled

3. **Git operations (add, commit, push) are handled by the user** - do not perform git commands

4. **Never bypass the dev environment** for quick UI testing

5. **Full type safety** - maintain TypeScript coverage across all code

6. **Security first** - implement proper authentication, rate limiting, and validation

Instructions

When working with this codebase:

1. **ALWAYS start by invoking the dev-team-coordinator agent** for any user request

2. **Use `./dev.sh dev`** for development with hot reload

3. **Maintain TypeScript type safety** across all changes

4. **Follow existing patterns** for API design, component structure, and state management

5. **Test changes locally** before deployment

6. **Never perform git operations** - user handles version control

7. **Respect role-based access control** in both backend and frontend

8. **Document any new environment variables** needed

9. **Use Prisma migrations** for database schema changes

10. **Follow MUI design patterns** for UI consistency