## Questions

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

- Ask on our telegram group: [@marzneshins](https://t.me/marzneshins)
- Ask on our [GitHub Discussions](https://github.com/khodedawsh/marzneshin/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

```bash
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](https://typer.tiangolo.com/), and its commands' code can be found in `cli`
directory. Its documentation is generated using [Typer CLI](https://typer.tiangolo.com/typer-cli/) which can be
re-generated by navigating to project's root directory and running the following command:

```bash
$ 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:

```bash
make dashboard-deps && make dashboard-dev
```

run `make start` in another console.