Webpanel

webpanel is a public fork of fastapi/full-stack-fastapi-template adapted for the VTB Family web panel. It keeps the base stack, but adds checkout-local development tooling, Redis and Taskiq background jobs, and an agent workflow built around canonical repo-local skills.

What This Repo Is

• FastAPI backend with SQLModel, Alembic, PostgreSQL, Redis, and Taskiq.
• React frontend built with Vite, TypeScript, Tailwind CSS, and shadcn/ui.
• Docker Compose based local and deployment workflows.
• Repo-local agent bootstrap with canonical skills in .agents/skills/.

This repository should be treated as a standalone product repo, not as a raw copy of the upstream template.

Quick Start

After cloning:

bash scripts/setup-agent-links.sh
bash scripts/check-agent-links.sh
uv run bash scripts/dev.sh start --random-ports
uv run bash scripts/dev.sh urls

The first two commands configure repo-local symlinks for:

• .codex/skills/
• .claude/skills/
• CLAUDE.md -> AGENTS.md

The dev helper starts a checkout-local stack and stores active ports and Compose project metadata in .devstack.env.

Local Architecture

The local development stack includes:

• PostgreSQL
• Redis
• FastAPI backend
• taskiq-worker
• frontend
• Mailcatcher

Important split:

• Taskiq + Redis is used for background job execution and result storage.
• FastStream + Redis + websocket/SSE is the intended pattern for realtime events when streaming is added.
• Durable state still belongs in the database and normal API endpoints.

Daily Workflow

Use the repository wrapper scripts by default:

uv run bash scripts/dev.sh start --random-ports
uv run bash scripts/dev.sh status
uv run bash scripts/dev.sh urls
uv run bash scripts/dev.sh stop
uv run bash scripts/dev.sh restart
uv run bash scripts/dev.sh down

Backend work:

uv sync --frozen --package app
uv run pytest
uv run bash backend/scripts/lint.sh

Frontend work:

bun install --frozen-lockfile --ignore-scripts
cd frontend && bun run lint
cd frontend && bun run test

If backend API changes, regenerate the frontend client:

cd frontend && bun run generate-client

Repo Conventions

• Canonical agent skills live only in .agents/skills/.
• .codex/skills/ and .claude/skills/ must contain symlinks created by bash scripts/setup-agent-links.sh.
• CLAUDE.md must stay a symlink to AGENTS.md.
• Generated frontend files under frontend/src/client/ and frontend/src/routeTree.gen.ts are not edited manually.
• .devstack.env is the only checkout-local stack state file.

For agent-specific rules, see AGENTS.md.

Realtime Event Work

For any work involving:

• event contracts
• FastStream
• Redis pub/sub
• websocket or SSE
• streaming progress or notifications

apply the realtime-events skill first.

The canonical skill source is:

• .agents/skills/realtime-events/SKILL.md

That skill defines:

• event schema requirements
• versioning rules
• publisher and subscriber patterns
• transport envelopes
• broadcaster responsibilities
• client snapshot and reconnect strategy

Documentation Map

• AGENTS.md - repo-local operating rules for agents and engineers
• development.md - day-to-day local development workflow
• deployment.md - deployment prerequisites and rollout flow
• docs/dev-stack-protocol.md - contract for scripts/dev.sh
• backend/README.md - backend-specific workflow notes
• frontend/README.md - frontend-specific workflow notes

Deployment

Deployments are Docker Compose based and assume a Traefik reverse proxy in front of the stack.

This repo uses deployment env files generated from the root .env template:

• .env.staging
• .env.prod

Generate them with:

bash scripts/generate-secrets.sh --staging
bash scripts/generate-secrets.sh --prod

See deployment.md for the full deployment flow.

Upstream

This repository remains a fork of:

• fastapi/full-stack-fastapi-template

That upstream history is intentional and should be preserved when possible.