Questions

Please don't ask your questions in issues. Instead, use one of the following ways to ask:

• Ask on our telegram group: @marzneshins
• Ask on our GitHub Discussions for long term discussion or larger questions.

Reporting issues

Include the following information in your post:

• Describe what you expected to happen.
• Describe what actually happened. Include server logs or any error that browser shows.
• If possible, post your xray json config file and what you have set in env (by censoring critical information).
• Also tell the version of Marzneshin, Xray and docker (if you use docker) you are using.

Submitting a Pull Request

If there is not an open issue for what you want to submit, prefer opening one for discussion before working on a PR. You can work on any issue that doesn't have an open PR linked to it or a maintainer assigned to it. These show up in the sidebar. No need to ask if you can work on an issue that interests you.

Branches

Make sure to create a branch off your master branch, and then submit a PR to our master branch.

Project Structure

.
├── app                      # Backend code (FastAPI - Python)
├── dashboard                # Frontend code (React - Typescript)
└── cli                      # CLI code (Typer - Python)

Backend

Backend is built using FastAPI and uses SQLAlchemy as the ORM for database operations. Pydantic models can be found in the app/models directory, while all database-related operations and models are in the app/db directory. The migration scripts for the database (Alembic) can be found in the app/db/migrations directory.

Python Code Formatting

To maintain consistency in the codebase, we require all code to be formatted using

black .

Frontend

The frontend follows a feature-oriented development structure. Features are essentially components, hooks, logics, services which provide user-experience that it coupled with domain and UI functionality.

Features

features folder encapsulate all features. Features can be categorized in few groups, Core domain, Support. Core domain features deliver a set of solutions to the problem the application intened to resolve. Meanwhile Support features provide a set of solutions that are independent from domain model, however, they are necessary for the application to fully deliver the experience the user expect.

Generic Components

components folder is a place for react generic components that will be reused by features. The same logic goes for hooks, types, folder.

Atomic components

components/ui folder is a place for atomic components that are the backbone of the application. These components are based on shadcn component template, however, depending when you are reading this, we probably have diverged a lot.

Utils

These functions are generic and reused across codebase, although, they will be transfered to their own generic folder or feature folder as they grow in complexity and code usage.

Routes and pages

routes folder is tanstack routing folder, containg pages and routing logic.

├── routes # @tanstack/react-router routing ├── features │ └── users # core domain feature │ └── nodes # core domain feature │ └── hosts # core domain feature │ └── entity-table # support feature │ └── github-repo # support feature ├── components │ └── ui # atomic components

To build the frontend you'll need the following dependencies:

• pnpm

then run make dashboard-deps && make dashboard build for it to build; or make dashboard-dev for development purposes.

Marzneshin CLI

Marzneshin CLI is built using Typer, and its commands' code can be found in cli directory. Its documentation is generated using Typer CLI which can be re-generated by navigating to project's root directory and running the following command:

$ PYTHONPATH=$(pwd) typer marzneshin-cli.py utils docs --name "marzneshin-cli" --output ./cli/README.md

Dev Mode

To run the frontend in development mode use the following commands to install the dependencies, and then run the backend:

make dashboard-deps && make dashboard-dev

run make start in another console.