Skip to content

Development

Jacob Bowen edited this page Mar 8, 2026 · 1 revision

Development Guide

This page covers setting up a local development environment, code conventions, and how to contribute to AzerothPanel.


Table of Contents

  1. Local setup (no Docker)
  2. Backend development
  3. Frontend development
  4. Code style & conventions
  5. Adding a new API endpoint
  6. Adding a new frontend page
  7. Validation checklist

Local Setup (no Docker)

Requirements

  • Python 3.11+
  • Node.js 20 LTS + npm
  • A running AzerothCore MySQL instance accessible from your machine
  • (Optional) A running worldserver for SOAP commands

Quick start

git clone https://github.com/scarecr0w12/AzerothPanel.git
cd AzerothPanel

make install          # installs backend + frontend deps

cp backend/.env.example backend/.env
# Set SECRET_KEY, PANEL_ADMIN_USER, PANEL_ADMIN_PASSWORD in backend/.env

make dev              # starts both processes with hot-reload
  • Backend: http://localhost:8000
  • Frontend: http://localhost:5173 (Vite HMR)
  • Swagger UI: http://localhost:8000/docs

Backend Development

Virtual environment

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Running with auto-reload

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Project layout

backend/app/
├── main.py             # App factory: registers routers, CORS, lifespan event
├── core/
│   ├── config.py       # Pydantic BaseSettings — all env vars typed here
│   ├── database.py     # Async SQLAlchemy engine + session factory + migrations
│   └── security.py     # JWT create/verify, password hashing, get_current_user
├── models/
│   ├── panel_models.py # SQLAlchemy ORM models (PanelSettings, etc.)
│   └── schemas.py      # Pydantic schemas for request/response bodies
├── api/v1/
│   ├── router.py       # Aggregates all endpoint routers under /api/v1
│   └── endpoints/      # One file per feature domain
├── api/websockets/
│   └── logs.py         # WebSocket handler for live log tailing
└── services/
    ├── panel_settings.py           # CRUD helpers for panel settings
    └── azerothcore/
        ├── server_manager.py       # Process start/stop
        ├── compiler.py             # Runs cmake/make, yields output lines
        ├── installer.py            # Runs AzerothCore installation steps
        ├── soap_client.py          # HTTP SOAP client (httpx)
        └── module_manager.py      # Git-based module install/remove

Adding a Python dependency

  1. Activate the venv: source backend/.venv/bin/activate
  2. Install: pip install <package>
  3. Freeze: pip freeze > backend/requirements.txt

Database migrations

Schema changes are applied via ALTER TABLE statements in backend/app/core/database.py:run_panel_db_migrations() guarded by try/except. This runs on every startup. To add a new column:

try:
    await conn.execute(text("ALTER TABLE my_table ADD COLUMN new_col TEXT"))
except Exception:
    pass  # column already exists

Frontend Development

Running the dev server

cd frontend
npm install
npm run dev

The Vite config proxies /api/ and /ws/ to http://localhost:8000.

Production build

cd frontend
npm run build    # outputs to frontend/dist/

Project layout

frontend/src/
├── App.tsx              # React Router routes
├── main.tsx             # Entry point
├── index.css            # Tailwind base
├── pages/               # Full-page views (one per route)
├── components/
│   ├── layout/          # Header, Sidebar, Layout wrapper
│   └── ui/              # Reusable primitives (Button, Card, StatusBadge)
├── hooks/
│   ├── useWebSocket.ts  # Generic WebSocket hook with reconnect
│   └── useServerStatus.ts
├── services/api.ts      # Axios instance + all typed API calls
├── store/index.ts       # Zustand global store (auth token, server state)
└── types/index.ts       # Shared TypeScript interfaces

Code Style & Conventions

Backend

  • Follow PEP 8; use 4-space indentation.
  • Use async def for all route handlers and service functions.
  • All request/response bodies are typed with Pydantic schemas in models/schemas.py.
  • Raise HTTPException with appropriate status codes; do not return raw error strings.
  • Business logic belongs in services/, not in endpoint handlers.
  • Use dependency injection (Depends) for auth, database sessions, and settings.

Frontend

  • TypeScript strict mode is enabled — no any types without justification.
  • Functional components with hooks only; no class components.
  • API calls live in services/api.ts; pages do not call axios directly.
  • Shared types go in types/index.ts.
  • Use Tailwind utility classes; avoid custom CSS unless unavoidable.

Adding a New API Endpoint

  1. Create or update the endpoint file in backend/app/api/v1/endpoints/:

    # backend/app/api/v1/endpoints/example.py
    from fastapi import APIRouter, Depends
    from app.core.security import get_current_user
    
    router = APIRouter(prefix="/example", tags=["Example"])
    
    @router.get("/hello")
    async def hello(_: dict = Depends(get_current_user)):
        return {"message": "Hello from the new endpoint"}
  2. Register it in the router (backend/app/api/v1/router.py):

    from app.api.v1.endpoints import example
    api_router.include_router(example.router)
  3. Add Pydantic schemas to backend/app/models/schemas.py if needed.

  4. Expose it in the frontend (frontend/src/services/api.ts):

    export const getHello = () =>
      api.get<{ message: string }>("/example/hello").then(r => r.data);

Adding a New Frontend Page

  1. Create the page component in frontend/src/pages/MyPage.tsx.

  2. Add the route in frontend/src/App.tsx:

    import MyPage from "./pages/MyPage";
    // inside <Routes>:
    <Route path="/my-page" element={<MyPage />} />
  3. Add a sidebar link in frontend/src/components/layout/Sidebar.tsx:

    { path: "/my-page", label: "My Page", icon: <SomeIcon /> }

Validation Checklist

Before committing, verify:

  1. TypeScript type check (must be zero errors):

    cd frontend && npx tsc --noEmit
  2. Frontend production build (must succeed):

    cd frontend && npm run build
  3. Python syntax check for any modified files:

    cd backend && source .venv/bin/activate
    python -m py_compile app/main.py

There are no automated tests in this project. Manual validation is required.

Clone this wiki locally