Documentation Index
Fetch the complete documentation index at: https://mintlify.com/IvanchoDev89/maleku-system/llms.txt
Use this file to discover all available pages before exploring further.
Maleku System is a monorepo containing a FastAPI (Python 3.11+) backend and a Nuxt.js 3 (Vue 3 + TypeScript) frontend. This guide walks you through every step needed to get both services running locally — either through Docker Compose for a zero-configuration start, or natively for the fastest possible feedback loop during active development.
Prerequisites
Before cloning the repository, make sure the following tools are available on your machine:
| Tool | Minimum version | Notes |
|---|
| Git | 2.30+ | Required for all workflows |
| Docker | 20.10+ | Required for Docker-based setup |
| Docker Compose | V2 (docker compose) | Bundled with Docker Desktop |
| Node.js | 18+ | Required for frontend development |
| Python | 3.11+ | Required for backend development |
| Make | Any | Optional — provides convenience targets |
On macOS, Docker Desktop ships with Compose V2 out of the box. On Linux, install the docker-compose-plugin package to enable the docker compose subcommand (no hyphen).
Fork and Clone
Start by forking the repository to your own GitHub account, then clone your fork locally and register the canonical repo as the upstream remote so you can keep your fork in sync.
# 1. Fork the repository on GitHub (click "Fork" in the top-right corner)
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/maleku-system.git
cd maleku-system
# 3. Add the upstream remote
git remote add upstream https://github.com/IvanchoDev89/maleku-system.git
# 4. Verify both remotes are configured
git remote -v
git pull upstream main to fetch the latest changes from the canonical repository before starting new work.
Option 1: Docker
Docker Compose is the recommended starting point because it provisions every dependency — PostgreSQL, Redis, MailHog, and both application services — with a single command and matches the configuration used in CI.
# Copy the environment templates
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
# Build images and start all services in the background
docker compose up -d
# Run database migrations
docker compose exec backend alembic upgrade head
| Service | URL |
|---|
| Frontend (Nuxt SSR) | http://localhost:3000 |
| Backend (FastAPI) | http://localhost:8000 |
| Interactive API docs (Swagger) | http://localhost:8000/docs |
| ReDoc | http://localhost:8000/redoc |
Hybrid mode for fast iteration — run the backend natively with uvicorn --reload for instant Python restarts while keeping only MailHog (and optionally Redis) in Docker. This lets you skip full image rebuilds on every backend change while still having a real mail-catching server available. Start the infrastructure-only services first, then run the backend and frontend natively as shown in Option 2.
Option 2: Native Development
If you want the fastest possible hot-reload cycle, run both services directly on your machine.
The backend is a standard Python package. Create a virtual environment, install dependencies from requirements.txt, configure your .env, then start the development server.cd backend
# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate # macOS / Linux
# venv\Scripts\activate # Windows
# Install all dependencies
pip install -r requirements.txt
requirements.txt include:| Package | Version |
|---|
fastapi | ≥0.115.0 |
uvicorn[standard] | ≥0.34.0 |
sqlalchemy | ≥2.0.36 (async) |
asyncpg | ≥0.30.0 |
alembic | ≥1.14.0 |
pydantic | ≥2.10.0 (v2) |
pydantic-settings | ≥2.7.0 |
PyJWT | ≥2.10.0 |
redis | ≥5.2.0 |
stripe | ≥11.0.0 |
sentry-sdk | ≥2.20.0 |
pytest | ≥8.3.0 |
pytest-asyncio | ≥0.25.0 |
# Copy the environment template and fill in your values
cp .env.example .env
# Start the development server with auto-reload
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
http://localhost:8000. Any change to a .py file triggers an automatic reload.You can also use the make convenience target from the repository root: The frontend is a Nuxt 3 application. Install Node.js dependencies, configure your .env, then start the Nuxt dev server.cd frontend
# Install all dependencies (runs nuxt prepare automatically via postinstall)
npm install
# Copy the environment template and fill in your values
cp .env.example .env
# Start the Nuxt development server
npm run dev
http://localhost:3000 with hot module replacement enabled. Any change to a .vue, .ts, or .css file refreshes the browser instantly.You can also use the make convenience target from the repository root:Key package.json scripts:| Script | Description |
|---|
npm run dev | Start Nuxt dev server with HMR |
npm run build | Build for production |
npm run generate | Static site generation |
npm run preview | Preview the production build |
npm run test | Run Vitest unit tests |
npm run test:watch | Vitest in watch mode |
npm run test:coverage | Vitest with coverage report |
Pre-commit Hooks
Maleku System uses pre-commit to enforce code quality checks before every commit. Install the hooks once after cloning:
# Install pre-commit (if not already available)
pip install pre-commit
# Register the hooks with Git
pre-commit install
.pre-commit-config.yaml and run automatically on every git commit:
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.11.6
hooks:
- id: ruff
args: [--fix]
- id: ruff-format
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v5.0.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: check-json
- id: check-merge-conflict
- id: check-added-large-files
- id: detect-private-key
- id: mixed-line-ending
args: [--fix=lf]
pre-commit run --all-files
# or
make pre-commit-run
The detect-private-key hook will block commits that contain private key material. Never hard-code secrets — keep all credentials in your .env file, which is listed in .gitignore.
Running Tests
Backend
Backend tests use pytest with pytest-asyncio for async endpoint testing. A lightweight aiosqlite database is used in-process so no external PostgreSQL instance is required for the unit test suite.
cd backend
# Run the full test suite
python -m pytest -v --tb=short -x
# Run with line-level coverage report
python -m pytest -v --tb=short --cov=app --cov-report=term-missing
# Run a single test file
pytest tests/test_auth.py
# Watch mode (re-runs on file changes)
make test-backend-watch
make test-backend # Run all backend tests
make test-backend-coverage # Run with coverage
Frontend
Frontend tests use Vitest with @vue/test-utils and happy-dom as the environment.
cd frontend
# Run tests once
npm run test
# Run tests in watch mode
npm run test:watch
# Run with V8 coverage report
npm run test:coverage
make test-frontend # Run frontend tests once (npx vitest run)
make test-frontend-watch # Vitest in watch mode
make test-frontend-coverage # Vitest with coverage
E2E Tests
End-to-end tests are powered by Playwright and configured at playwright.config.ts in the repository root. Tests live under the e2e/ directory and run against three browser targets: Chromium (Desktop Chrome), Firefox, and Mobile Chrome (Pixel 5).
The Playwright config uses http://localhost:3000 as baseURL and automatically starts the Nuxt dev server (or production build in CI) as a webServer:
// playwright.config.ts (excerpt)
webServer: {
command: process.env.CI
? 'npm run build && npm run start'
: 'npm run dev',
url: 'http://localhost:3000',
reuseExistingServer: !process.env.CI,
cwd: './frontend',
},
npx playwright test
# or
make test-e2e
2 and workers to 1 to reduce flakiness. Locally, tests run fullyParallel with no retries for speed.
Playwright browsers must be installed before first use. Run npx playwright install from the repository root to download Chromium, Firefox, and the mobile Chrome emulator.
