Quick Start

Overview

This guide will walk you through launching the application, logging in for the first time, and exploring the main interface of Tattoo Studio Manager.

Before proceeding, ensure you have installed the application and completed the initial setup wizard.

Launching the Application

Activate Virtual Environment

First, activate your Python virtual environment:

cd C:\path\to\TattoStudio
.venv\Scripts\activate.bat

Using the start.bat Shortcut (Windows)

On Windows, you can use the included batch file:

start.bat

@echo off
cd /d "%~dp0"
call .venv\Scripts\activate.bat
python main.py
pause

Simply double-click start.bat in the project folder.

Run the Application

Launch the application:

python main.py

The application loads in this order:

Initializes the theme (light/dark mode from settings)
Verifies database connection
Opens the login dialog
Loads the main window after successful authentication

When the application starts, you’ll see the InkLink OS login screen.

Default Test Accounts

If you seeded the database with sample data, you can use these test accounts:

Administrator

Username: admin
Password: admin123Full system access

Assistant

Username: assistant
Password: assistant123Studio operations access

Artist

Username: jesus
Password: tattoo123Artist-specific access

Authentication Process

The login system uses secure bcrypt password hashing:

services/auth.py

def authenticate(db: Session, username: str, password: str) -> Optional[Dict]:
    """Authenticates user and returns profile if credentials are valid."""
    u = get_user_by_username(db, username)
    if not u or not u.is_active:
        return None
    if not verify_password(password, u.password_hash):
        return None

    # Update last login timestamp
    u.last_login = datetime.utcnow()
    db.commit()

    return {
        "id": u.id,
        "username": u.username,
        "role": u.role,
        "artist_id": u.artist_id,
    }

If you don’t have any users in the database, the First Run Wizard will automatically appear to guide you through creating an admin account.

Understanding the Main Interface

After logging in, you’ll see the main window with three main areas: The top bar contains:

Studio Logo & Name (left): Your configured branding
Navigation Pills (center): Main sections of the app
User Button (right): Access to settings and logout

ui/main_window.py

self.btn_studio  = self._pill("Estudio")    # Studio dashboard
self.btn_sched   = self._pill("Agenda")     # Appointment scheduler  
self.btn_clients = self._pill("Clientes")   # Client management
self.btn_staff   = self._pill("Staff")      # Staff management
self.btn_reports = self._pill("Reportes")   # Reports & analytics
self.btn_forms   = self._pill("Inventario") # Inventory (admin only)

2. Main Content Area

The center area displays the current page:

The Studio page is your home screen with quick actions:

Create new appointment
Add new client
Open cash register
View portfolios
Studio statistics overview

ui/main_window.py

self.studio_page = StudioPage(
    studio_name=self.studio_name,
    logo_path=self._studio_logo_override,
)

The Agenda page manages appointments:

Day/week/month calendar views
Create and edit appointments
Assign artists to sessions
Track appointment status (Active, Completed, Waiting)
Time slot configuration

Configure schedule hours in Settings:

settings.json

{
  "agenda_hours": {
    "start": "08:00",
    "end": "21:30",
    "step": 30  // minutes per time slot
  }
}

The Clients page handles customer management:

Search and filter clients
Add new clients with contact info
View client history and sessions
Track preferences and preferred artist
Manage client portfolios

Client model includes:

data/models/client.py

name           # Full name
phone          # Contact number
email          # Email address
instagram      # Social media handle
preferred_artist_id  # Favorite artist
is_active      # Active status

The Staff page manages your team:

View all artists and assistants
Add new staff members
Set commission rates for artists
Link user accounts to staff profiles
Track artist performance

data/models/artist.py

name              # Artist name
rate_commission   # Commission percentage (0.0-1.0)
active            # Active status

The Inventory section (admin only):

Product catalog
Stock levels and alerts
Product entries and adjustments
Movement history
Low stock warnings

data/models/product.py

sku        # Product code
name       # Product name
category   # Product category
stock      # Current quantity
min_stock  # Reorder threshold
cost       # Unit cost

3. Status Bar

The bottom status bar displays:

Application version
Last backup timestamp
System notifications

ui/main_window.py

self.statusBar().showMessage(f"Ver. 1.0.1 | Último respaldo {last}")

Role-Based Access Control (RBAC)

The application implements role-based access to protect sensitive features:

Admin
Assistant
Artist

Full System AccessAdministrators can:

Access all pages and features
Manage inventory
Create and modify staff accounts
Configure system settings
Create/restore backups
View all reports

ui/main_window.py

if role == "admin":
    allowed |= {
        self.idx_clientes, self.idx_cliente_det,
        self.idx_staff, self.idx_staff_det,
        self.idx_inventory, self.idx_inv_items,
        # ... all indices
    }

Limited Personal AccessArtists can:

View their own schedule
View client information
See basic reports
View staff directory

Artists cannot:

Modify schedules
Create/edit clients
Access inventory
View financial reports
Manage staff

ui/main_window.py

elif role == "artist":
    allowed |= {
        self.idx_clientes, self.idx_cliente_det,
        self.idx_staff, self.idx_staff_det,
    }

If a user attempts to access a restricted page, they’re automatically redirected to the Studio dashboard with a status message.

User Panel

Click your username in the top-right corner to open the user panel:

Theme Toggle

Switch between light and dark mode

Settings

Configure studio info, schedule hours, and backups

About

View application version and information

Logout

Sign out and return to login screen

Common Tasks

Create a New Client

Navigate to Clientes (Clients)
Click the + Nuevo Cliente button
Fill in client information:
- Name (required)
- Phone and email
- Instagram handle
- Preferred artist
Click Guardar (Save)

ui/pages/new_client.py

# Client dialog opens as a modal popup
dlg = NewClientDialog(self)
dlg.exec_()

Schedule an Appointment

Navigate to Agenda (Schedule)
Select a date and time slot
Click to create a new session
Fill in appointment details:
- Client (search or create new)
- Artist
- Start and end time
- Price
- Notes
Click Guardar (Save)

The session is created with status “Activa” (Active).

Process a Payment

Click Caja (Cash Register) from the Studio dashboard
Select a completed session
Enter payment details:
- Amount
- Payment method (Cash, Card, Transfer)
- Date
Confirm transaction

data/models/transaction.py

session_id    # Linked tattoo session
artist_id     # Artist who performed work
amount        # Payment amount
method        # Payment method
date          # Transaction date

Switch User Accounts

Click your username (top-right)
Click Cerrar sesión (Logout)
The login screen appears
Enter different credentials

The application maintains session state and applies role-based restrictions automatically.

Change Application Theme

Click your username (top-right)
Toggle the Modo oscuro (Dark mode) switch

Theme preference is saved to settings.json and persists across sessions:

main.py

def load_theme_preference() -> str:
    if SETTINGS.exists():
        try:
            return json.loads(SETTINGS.read_text()).get("theme", "light")
        except Exception:
            pass
    return "light"

Keyboard Shortcuts

Login Screen

Enter: Submit login form
Esc: Close application

Main Window

Alt + Q: Quick search clients
Ctrl + N: New appointment
Ctrl + ,: Open settings

Data Management

Automatic Backups

The application automatically creates database backups:

services/backups.py

def create_backup_if_needed():
    """Creates backup if more than 24 hours since last backup."""
    # Checks last backup time
    # Creates timestamped backup: backup_YYYYMMDD_HHMMSS.db
    # Stores in backups/ directory

Backups are stored in the backups/ folder with timestamps:

backup_20260304_091530.db
backup_20260303_184522.db

Backups are created automatically on application start if more than 24 hours have passed since the last backup.

Manual Backup

To create a manual backup:

Click your username → Ajustes (Settings)
Go to the Respaldos (Backups) tab
Click Crear respaldo ahora (Create backup now)

Restore from Backup

Open Settings → Backups tab
Select a backup from the list
Click Restaurar respaldo seleccionado (Restore selected backup)
Confirm the restoration
Restart the application to apply changes

Restoring a backup will replace your current database. The current database is automatically backed up before restoration, but you should always verify your backups are working properly.

Next Steps

Now that you’re familiar with the basics, explore more advanced features:

Client Onboarding

Learn how to register new clients with consent forms

Inventory Management

Set up products and track stock levels

Financial Reports

Generate insights from your studio data

Portfolio Management

Organize and showcase artist work

Troubleshooting

Can't Log In

Verify credentials are correct (usernames are case-sensitive)
Check if account is marked as active
Try resetting password through database (if admin access available)
Check console for error messages

Missing Menu Items

Database Locked Error

If you see “database is locked”:

Close all instances of the application
Wait 30 seconds
Relaunch the application

SQLite allows only one write operation at a time.

Theme Not Saving

If your theme preference doesn’t persist:

Check file permissions on settings.json
Verify the file isn’t read-only
Check console for JSON parsing errors

Delete settings.json to reset to defaults (will clear all settings).

Getting Help

If you encounter issues:

Check the application logs in the console
Review the Installation Guide for setup issues
Check the First-Time Setup Guide for configuration help
Contact your system administrator

Get Started

Core Features

User Roles

Guides

Overview

Launching the Application

Default Test Accounts

Administrator

Assistant

Artist

Authentication Process

Understanding the Main Interface

1. Top Navigation Bar

2. Main Content Area

3. Status Bar

Role-Based Access Control (RBAC)

User Panel

Theme Toggle

Settings

About

Logout

Common Tasks

Keyboard Shortcuts

Login Screen

Main Window

Data Management

Automatic Backups

Manual Backup

Restore from Backup

Next Steps

Client Onboarding

Inventory Management

Financial Reports

Portfolio Management

Troubleshooting

Getting Help

Build docs developers (and LLMs) love

Get Started

Core Features

User Roles

Guides

​Overview

​Launching the Application

​First Login

​Default Test Accounts

Administrator

Assistant

Artist

​Authentication Process

​Understanding the Main Interface

​1. Top Navigation Bar

​2. Main Content Area

​3. Status Bar

​Role-Based Access Control (RBAC)

​User Panel

Theme Toggle

Settings

About

Logout

​Common Tasks

​Keyboard Shortcuts

Login Screen

Main Window

​Data Management

​Automatic Backups

​Manual Backup

​Restore from Backup

​Next Steps

Client Onboarding

Inventory Management

Financial Reports

Portfolio Management

​Troubleshooting

​Getting Help

Build docs developers (and LLMs) love

Overview

Launching the Application

First Login

Default Test Accounts

Authentication Process

Understanding the Main Interface

1. Top Navigation Bar

2. Main Content Area

3. Status Bar

Role-Based Access Control (RBAC)

User Panel

Common Tasks

Keyboard Shortcuts

Data Management

Automatic Backups

Manual Backup

Restore from Backup

Next Steps

Troubleshooting

Getting Help