Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: developer guide #4

Merged
merged 5 commits into from
Jul 29, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
name: Docs CI

on:
push:
branches: ["main"]
pull_request:

concurrency:
group: "pages"
cancel-in-progress: false

defaults:
run:
shell: bash

jobs:
build:
runs-on: ubuntu-latest
env:
HUGO_VERSION: 0.126.3
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0 # fetch all history for .GitInfo and .Lastmod
submodules: recursive
- name: Setup Go
uses: actions/setup-go@v5
with:
go-version: "1.22"
- name: Setup Pages
id: pages
uses: actions/configure-pages@v4
- name: Setup Hugo
run: |
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
&& sudo dpkg -i ${{ runner.temp }}/hugo.deb
- name: Build with Hugo
env:
# For maximum backward compatibility with Hugo modules
HUGO_ENVIRONMENT: production
HUGO_ENV: production
run: |
hugo \
--gc --minify \
--baseURL "${{ steps.pages.outputs.base_url }}/"
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./public
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Sample workflow for building and deploying a Hugo site to GitHub Pages
name: Deploy Hugo site to Pages
name: Deploy

on:
# Runs on pushes targeting the default branch
Expand Down
4 changes: 0 additions & 4 deletions content/docs/contribution-guide/_index.md

This file was deleted.

Empty file.
52 changes: 52 additions & 0 deletions content/docs/developer-guide/_index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
---
title: Developer Guide
weight: 4
---

# Contribution Guideline

This series of documents is dedicated to people whom want to understand
the codebase, architecture, and the contribution guideline.

### 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.

{{< callout type="warning" >}}

Please don't open issues solely intended to **questions**. 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.

{{< /callout >}}

### 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.

{{< callout type="warning" >}}

Your PR name must follow the angular [commit conventions](https://www.conventionalcommits.org) `action(scope): desc`.
Otherwise your PR will be marked as broken and does not pass CI pipeline.

{{< /callout >}}

#### CI

There are several actions quality checking your code. Make sure you pass all criteria's, especially **Sonar**.

#### Branches

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

The naming convetion for branches is `action/scope` plus the the number of issue if
there is one related. E.g. `feat/users-filter-admin`, `fix/nodes-settings-tab-123`.
139 changes: 139 additions & 0 deletions content/docs/developer-guide/codebase.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
---
title: Codebase
next: support
prev: docs/developer-guide
toc: true
weight: 1
---

## Project Structure

To rewrite the provided folder structure using the `filetree` notation based on the documentation in the image, the code will look like this:

{{< filetree/container >}}
{{< filetree/folder name="marzneshin" state="open">}}
{{< filetree/folder name="app" >}}
Backend code
{{< /filetree/folder >}}
{{< filetree/folder name="dashboard" >}}
Frontend Code
{{< /filetree/folder >}}
{{< filetree/folder name="cli" >}}
CLI Code
{{< /filetree/folder >}}
{{< /filetree/folder >}}
{{< /filetree/container >}}

| Folder name | Description |
| ----------- | ---------------------------------- |
| `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.

{{< filetree/container >}}
{{< filetree/folder name="routes" >}}
{{< /filetree/folder >}}
{{< filetree/folder name="features" >}}
{{< filetree/folder name="users" >}}
{{< /filetree/folder >}}
{{< filetree/folder name="nodes" >}}
{{< /filetree/folder >}}
{{< filetree/folder name="hosts" >}}
{{< /filetree/folder >}}
{{< filetree/folder name="entity-table" >}}
{{< /filetree/folder >}}
{{< filetree/folder name="github-repo" >}}
{{< /filetree/folder >}}
{{< /filetree/folder >}}
{{< filetree/folder name="components" >}}
{{< filetree/folder name="ui" >}}
{{< /filetree/folder >}}
{{< /filetree/folder >}}
{{< /filetree/container >}}

| Folder name | Description |
| -------------- | ------------------------------ |
| `routes` | @tanstack/react-router routing |
| `features` | Feature folder |
| `users` | Core domain feature |
| `nodes` | Core domain feature |
| `hosts` | Core domain feature |
| `entity-table` | Support feature |
| `github-repo` | Support feature |
| `components` | Generic Components |
| `ui` | Atomic components |

### 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.

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.