🚀 Project Setup & Development Guide

📋 Table of Contents

• Getting Started
• Project Management
• Code Quality
• Development Workflow

---

Getting Started

🔄 Clone Project (Quick Start)

View Steps

1. Clone the repository

git clone git@gitlab.com:public-projects1853809/dash-mantine-template.git

2. Navigate to project directory

cd dash-mantine-template

3. Create PostgreSQL database

Use this docker-compose.yml configuration:

services:
  db:
    image: postgres:15  
    container_name: postgres_db
    restart: always
    environment:
      POSTGRES_USER: myuser
      POSTGRES_PASSWORD: mypassword
      POSTGRES_DB: mydatabase
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

4. Run the application

uv run my-new-app

---

🎯 Clone Project with Custom Name

View Steps

1. Create new package

uv init --package my-new-app

2. Clone dash-mantine-project

git clone git@gitlab.com:public-projects1853809/dash-mantine-template.git

3. Clean the new project folder

cd my-new-app
rm -rf *
rm .gitignore
rm .python-version

4. Copy template files

Copy everything from dash-mantine-project to my-new-app folder

5. Update pyproject.toml

Before:

name = "dash-mantine-template"
authors = [
    { name = "Milan Mitrovic", email = "milanmitrovic1991@gmail.com" }
]
[project.scripts]
dash-mantine-template = "dash_mantine_template:main"

After:

name = "my-new-app"
authors = [
    { name = "Name Surname", email = "user@email.com" }
]
[project.scripts]
my-new-app = "my_new_app:main"

6. Rename source folder

mv src/dash_mantine_template/ src/my_new_app/

7. Update imports in pages/ folder

Before:

from dash_mantine_template.components.filters.XYZ import (
    ZXY,
)

After:

from my_new_app.components.filters.radio_button import (
    radio_button__component,
)

8. Update HTML template filepath

Before:

with open(
    "src/dash_mantine_template/components/miscellaneous/InitialTheme.html",
    "r",
    encoding="utf-8",
) as file:
    html_string = file.read()

After:

with open(
    "src/my_new_app/components/miscellaneous/InitialTheme.html",
    "r",
    encoding="utf-8",
) as file:
    html_string = file.read()

9. Create PostgreSQL database

Use the same docker-compose.yml from Quick Start section

10. Run the application

uv run my-new-app

11. Update test imports

find tests/ -type f -name "*.py" -exec sed -i '' 's/from my_new_app\./from dash_mantine_template./g' {} +

---

Project Management

📦 Dependencies

Sync project dependencies

uv sync --dev

Add project dependency

uv add python_package_name

Add development dependency

uv add --dev package_name

Install with dev dependencies

uv sync --dev

---

🔧 Pre-commit Hooks

1. Auto-update hook versions

uv run pre-commit autoupdate

2. Reinstall hooks

uv run pre-commit install --install-hooks

3. Run hooks

# Run on staged files
uv run pre-commit run

# Run on all files
uv run pre-commit run --all-files

---

▶️ Running the Project

Start application

uv run dash-mantine-template

---

Code Quality

🧪 Testing

Run tests

uv run pytest .

Generate coverage report

COVERAGE_FILE=temp/coverage_data/.coverage uv run python -m pytest --cov .

Save coverage report as HTML

COVERAGE_FILE=temp/coverage_data/.coverage pytest --cov=. --cov-report=html:temp/coverage_report/html --cov-report=xml:temp/coverage_report/xml/coverage.xml

---

✨ Code Formatting & Linting

Run ruff linter

uv run ruff check

Auto-fix linter issues

uv run ruff check --fix

Format code

uv run ruff format

Sort imports

uv run ruff check --select I --fix

---

✅ Pre-commit Checklist

Before each commit, ensure you:

• ✓ Run PyTest
• ✓ Sort imports
• ✓ Format code
• ✓ Lint code

---

🗄️ Database Migrations (Pyway)

# View migration info
uv run pyway info

# Validate migrations
uv run pyway validate

# Run migrations
uv run pyway migrate

# Import (TBD)
# Checksum (TBD)

---

Development Workflow

🌿 Branch Strategy

Branch Types:

• main - Production-ready code
• develop - Integration branch for features
• feature/branch_name - Feature development
• release/branch_name - Release preparation

---

🏷️ Tagging Convention

• test-version_number - Test environment
• uat-version_number - UAT environment
• prod-version_number - Production environment

---

🚢 Deployment Strategy

Three-tier deployment process:

Environment	Tag Pattern	Permission Level
TEST	test-version_number	Developer
UAT	uat-version_number	Higher Authority I
PROD	prod-version_number	Higher Authority II

How it works:

• Deployment is triggered when a TAG with specific name pattern is created
• Different CICD pipelines run based on TAG name
• User permissions determine which TAGs can be created

---

🔄 Workflow Process

1. Create feature branch from develop
2. Merge feature into develop
3. Create release branch from develop
4. Deploy release branch to UAT
5. Iterate on feedback (on release or develop branch?)
6. Handle concurrent feature development after release candidate creation

Open Questions:

• Where to iterate user feedback? Release or develop branch?
• How to handle features being developed after RC branch creation?
  • Merge changes into develop or wait?

---

📝 Git Workflow

1. Create issue
2. Create Pull/Merge Request
3. (To be continued...)

---

Last updated: January 2026