Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
209 lines (138 loc) · 5.48 KB

CONTRIBUTING.md

File metadata and controls

209 lines (138 loc) · 5.48 KB
Raw

Contribute to PasarGuard

Thanks for considering contributing to PasarGuard!

🙋 Questions

Please don’t use GitHub Issues to ask questions. Instead, use one of the following platforms:

🐞 Reporting Issues

When reporting a bug or issue, please include:

  • ✅ What you expected to happen
  • ❌ What actually happened (include server logs or browser errors)
  • ⚙️ Your xray JSON config and .env settings (censor sensitive info)
  • 🔢 Your PasarGuard version and Docker version (if applicable)

🚀 Submitting a Pull Request

If there's no open issue for your idea, consider opening one for discussion before submitting a PR.

You can contribute to any issue that:

  • Has no PR linked
  • Has no maintainer assigned

No need to ask for permission!

🔀 Branching Strategy

  • Always branch off of the next branch
  • Keep main stable and production-ready

📁 Project Structure

.
├── app          # Backend code (FastAPI - Python)
├── cli          # CLI code (Typer - Python)
├── dashboard    # Frontend code (React Router - TypeScript)
└── tests        # API tests

⚙️ Development Setup

The project uses uv for Python dependency management and bun for frontend dependencies.

🐍 Backend Setup

  1. Install uv if you haven't already.
  2. Initialize the virtual environment and install dependencies: 
    make setup
  3. Run database migrations: 
    make run-migration
  4. Start the application: 
    make run

💻 Frontend Setup

  1. Install bun if you haven't already.
  2. Install frontend dependencies: 
    make install-front

🧠 Backend (FastAPI)

The backend is built with FastAPI and SQLAlchemy:

  • Pydantic models: app/models/
  • Database structure: app/db/
    • SQLAlchemy models: app/db/models.py
    • Database CRUD operations: app/db/crud/
    • Alembic migrations: app/db/migrations/
  • Core backend logic: app/operation/
  • API Routers: app/routers/

🧩 Note: Ensure all core backend business logic is organized and implemented in the app/operation module. This keeps route handling, database access, and service logic clearly separated and easier to maintain.

📘 API Docs (Swagger / ReDoc)

Enable the DOCS flag in your .env file to access:

🎯 Code Formatting & Linting

Format and lint backend Python code with:

make check
make format

🗃️ Database Migrations

Apply Alembic migrations to your database:

make run-migration

Check migrations integrity:

make check-migrations

💻 Frontend (React + Tailwind)

⚠️ We no longer upload pre-built frontend files.

The frontend is located in the dashboard/ directory and is built using:

  • React Router 7 + TypeScript
  • Tailwind CSS v4 + Shadcn UI
  • Orval (for API client generation)

🔄 API Client Generation

The frontend uses generated API clients via Orval. If you change backend routes or models, regenerate the TypeScript client by running:

make gen-api

🎯 Code Formatting

Format frontend code using Prettier:

make fformat

🧩 Component Guidelines

  • Follow Tailwind + Shadcn best practices.
  • Keep components single-purpose.
  • Prioritize readability and maintainability.

🛠️ PasarGuard CLI

PasarGuard’s CLI is built using Typer.

  • CLI codebase: cli/ and the entrypoint script pasarguard-cli.py.
  • To run the CLI in development: 
    make run-cli

🧪 Testing

We use pytest for backend tests.

  • Run tests: 
    make test
  • Run tests in watch mode: 
    make test-whatch

🐛 Debug Mode

To run the project in debug mode with auto-reload, set DEBUG=true in your .env file.

When you run make run (or uv run main.py) with DEBUG=true:

  1. The backend FastAPI server starts in reload mode via Uvicorn.
  2. The frontend Vite dev server (bun run dev) automatically spins up on a separate port.
  3. The API client generator runs in the background to keep the frontend types in sync.

Install frontend dependencies first before running in debug mode:

make install-front

💡 Note: In production mode (DEBUG=false), the backend will check if the dashboard/build directory exists. If it doesn't, it will build the frontend once using bun run build and then mount and serve the static files from dashboard/build/ at /dashboard/.

Feel free to reach out via Telegram or GitHub Discussions if you have any questions. Happy contributing! 🚀