Financial Tracking

Overview

The Financial Tracking system provides complete visibility into your studio’s revenue, expenses, and artist commissions. Track every payment, generate detailed reports, and analyze financial performance with powerful filtering and visualization tools.

Core Concepts

Transaction Model

Every payment is recorded as a transaction:

id: Integer (primary key)
session_id: Integer (Foreign Key → TattooSession, optional)
artist_id: Integer (Foreign Key → Artist, required)

amount: Float - Total collected
method: String - Payment method ("Efectivo", "Tarjeta", "Transferencia", "Mixto")
concept: String(200) - Free-text description
date: DateTime - When payment occurred

commission_amount: Float - Calculated commission
deleted_flag: Boolean - Soft delete (default: False)

created_at: DateTime - Record creation timestamp  
updated_at: DateTime - Last modification timestamp

Multiple Transactions Per Session

Sessions can have multiple payment transactions:

Deposit - Initial payment to reserve time
Final payment - Balance after session completion
Tip - Additional gratuity
Refund - Negative amount for returns

The system tracks:

total_paid - Sum of all non-deleted transactions
balance - Remaining amount owed (price - total_paid)

Soft delete (deleted_flag) allows “removing” transactions while preserving audit history. Deleted transactions don’t count toward totals.

Reports Page

Time Period Selection

Filter by predefined or custom date ranges: Quick Periods (clickable chips):

Today - Current day only
This Week - Sunday to Saturday of current week
This Month - First to last day of current month
Custom Range - Select any from/to dates

When “Custom Range” selected:

Date pickers appear for start and end dates
Calendar popup for easy selection
Range validation (end >= start)

Filters

Artist Filter

Dropdown with all active artists
“All Artists” to see studio-wide totals
Artists see only their own data (auto-locked)

Payment Method Filter

All payment types
Cash only (“Efectivo”)
Card only (“Tarjeta”)
Transfer only (“Transferencia”)

Artist role users cannot change the artist filter - they only see their own transactions for privacy and security.

Transaction Table

Detailed list of all matching transactions:

Column	Description
Date	Payment date (dd/MM/yyyy)
Client	Client name or ”—” for standalone payments
Amount	Total payment in currency format ($X,XXX.XX)
Payment	Payment method
Artist	Artist who performed the service

Table Features:

Sortable columns (click header)
Alternating row colors for readability
Right-aligned numeric amounts
Read-only (view-only, no inline editing)

Revenue Chart

Line graph showing daily revenue trends: Chart Features:

X-axis: Days in selected period (dd/MM format)
Y-axis: Revenue amount ($X format)
Multiple series: One line per artist (when viewing all)
Color coding: Matches artist colors from system
Interactive legend: Click to show/hide artist lines
Hover tooltips: Show exact values on data points
Auto-scaling: Y-axis adjusts to data range

Line Styling:

2px width for clarity
Colored by artist (from artist_colors.json)
Points visible at each data point
Smooth antialiasing

Smart Label Spacing:

Shows ~10 X-axis labels for readability
45° angle for longer date ranges (>14 days)
All dates plotted, only subset labeled

The chart only displays artists with revenue >$0 in the selected period to reduce clutter. Use the artist filter to focus on a specific artist.

Total Revenue Display

Prominent total in header:

Large, bold font for quick scanning
Currency formatted: $X,XXX.XX
Updates live as filters change
Period label shows what the total represents

Payment Processing

Recording a Payment

Open Payment Dialog

From appointment detail or cash register:

Click “Process Payment” or “Complete Session”
Payment dialog opens

Enter Amount

Type total payment amount

Range: $0.00 to$ 1,000,000.00
Two decimal precision
50¢ step increment

Set Commission

Enter artist commission percentage

Range: 0.00% to 100.00%
Default from artist settings
Override per transaction if needed

Commission amount auto-calculates:

Commission $ = Amount × Commission % ÷ 100

Select Payment Method

Choose from dropdown:

Cash (“Efectivo”)
Card (“Tarjeta”)
Transfer (“Transferencia”)
Mixed (“Mixto”) - for split payments

Add Note (Optional)

Enter reference or details:

Transaction ID from card processor
Check number
Payment plan installment (“2 of 3”)
Special terms or conditions

Confirm

Click OK to save transactionSystem records:

Transaction with all details
Links to session (if from appointment)
Updates session balance
Calculates commission

Commission Calculation

Commissions are calculated two ways: 1. Standard Commission (most common):

commission_amount = amount × (commission_pct / 100)

Example:

500 service × 40% commission =

200 2. Session Override (special cases):

commission_amount = amount × (session.commission_override / 100)

Used when:

Artist has special rate for this client
Promotional pricing affects commission
Apprentice vs. senior artist rates differ
Complex multi-artist collaboration

Commission overrides are set on the session, not the transaction. All transactions for that session use the override percentage.

Export Functionality

Export Dialog

Click Export CSV button: Export Scope Options:

Current View - Exports filtered results
- Respects artist filter
- Respects payment method filter
- Uses selected date range
All Data - Exports everything
- Ignores all filters
- Uses selected date range only
- Includes all artists and payment types
Cancel - Abort export

CSV Format

Exported file contains:

Date,Client,Amount,Payment,Artist
2026-03-04,John Smith,450.00,Efectivo,Alex Rivera
2026-03-04,Jane Doe,780.00,Tarjeta,Sam Chen
...

Field Details:

Date: YYYY-MM-DD (ISO format for sorting)
Client: Full name or ”—” for standalone
Amount: Decimal with 2 places (no $ symbol)
Payment: Exact method string
Artist: Full artist name

File Naming:

reportes_hoy_vista.csv - Today, current view
reportes_semana_todos.csv - This week, all data
reportes_20260301-20260315_vista.csv - Custom range, current view

Files use UTF-8 with BOM encoding for perfect Excel compatibility. Double-click to open directly in Excel without import wizard.

Export Permissions

Role	Can Export
Admin	✓ All data
Assistant	✓ With elevation approval
Artist	✓ Own data only

Assistant Elevation Flow:

Click Export CSV
System prompts for admin password
Admin enters credentials
Export proceeds if approved
Audit log records the elevated action

Auto-Refresh

The reports page automatically refreshes: Transaction Refresh (every 6 seconds):

Re-queries database for new transactions
Updates table and chart
Recalculates totals
Reloads active artists list

Color Refresh (every 2.5 seconds):

Checks artist_colors.json for changes
Reapplies colors to chart lines
Maintains color consistency with calendar

Benefits:

See payments from cash register in real-time
Multi-user studios stay synchronized
No manual refresh needed
Smooth updates without page flicker

Refresh timers only run when the Reports tab is visible. They pause when you switch tabs to save resources.

Financial Dashboards

Key Performance Indicators (KPIs)

Track these metrics in reports: Revenue Metrics:

Total Revenue - Sum of all transactions
Average Transaction - Mean payment amount
Revenue Per Artist - Individual performance
Revenue Per Day - Daily averages

Payment Mix:

Cash Percentage - Cash vs. other methods
Card Percentage - Card payment ratio
Transfer Percentage - Bank transfer ratio

Artist Metrics:

Commission Paid - Total artist earnings
Studio Revenue - After commission
Sessions Completed - Count per artist
Average Session Value - Revenue per session

Trend Analysis

Use the line chart for insights: Patterns to Look For:

Seasonal trends - Busy/slow seasons
Weekly patterns - Best/worst days
Growth trends - Increasing/decreasing revenue
Artist comparison - Performance relative to peers

Chart Interactions:

Click legend items to hide/show artists
Hover data points for exact values
Compare multiple artists visually
Export data for deeper analysis in Excel

Best Practices

Daily Reconciliation

End-of-day routine:

Export today’s transactions
Count physical cash in register
Compare total cash transactions to physical count
Reconcile card payments with merchant statements
Note any discrepancies in cash register log
Store daily report in accounting folder

Why reconcile daily:

Catch errors immediately
Prevent small losses from accumulating
Maintain accurate books
Simplify month-end closing

Commission Management

Set clear commission policies:

Document standard commission percentages
Define override criteria in writing
Communicate changes to artists in advance
Track commission changes over time

Use overrides sparingly:

Only for specific, justifiable situations
Document reason in session notes
Inform artist of the override
Review overrides monthly

Payment Method Tracking

Why track payment methods:

Merchant fees affect card profitability
Cash requires secure handling
Transfers have different processing times
Tax reporting varies by method

Mixed payment protocol:

Create separate transactions for each portion
Link all to same session
Note split in concept field
Example: “ $300 card +$ 200 cash”

Financial Reporting

Monthly reports to generate:

Total studio revenue
Revenue by artist
Revenue by payment method
Commission summary
Outstanding balances
Comparison to previous month

Annual reports:

Year-over-year growth
Seasonal trends
Artist performance rankings
Tax preparation summaries

Appointment Scheduling - Link payments to sessions
Client Management - Track payment history per client
Artist Portfolios - Connect revenue to portfolio pieces

Technical Details

Database Indexes

Optimized for fast reporting:

INDEX ix_tx_date ON transactions (date)
INDEX ix_tx_artist_date ON transactions (artist_id, date)

Enables efficient:

Date range queries
Artist-specific reports
Time-series aggregations

Transaction Timestamps

Three timestamp fields:

date - When payment occurred (user-selectable, for reports)
created_at - When record was created (audit trail)
updated_at - Last modification (change tracking)

The date field is used for all financial reporting and should represent the actual payment date, not the record creation date.

Soft Delete Implementation

deleted_flag: Boolean = False

# Query active transactions
active = session.query(Transaction).filter(
    Transaction.deleted_flag == False
)

# "Delete" without removing
txn.deleted_flag = True

Benefits:

Audit compliance
Reversible deletions
History preservation
Fraud detection

Troubleshooting

Totals Don't Match

Check for:

Deleted transactions (soft-deleted with flag)
Date range misalignment
Artist filter excluding some data
Payment method filter active
Time zone issues (check transaction.date)

To fix:

Clear all filters and recalculate
Check deleted_flag in database
Verify date ranges include all payments
Export to CSV and sum in Excel to verify

Chart Not Displaying

Possible causes:

PyQt5.QtChart module not installed
No data in selected period
All artists have $0 revenue
Artist filter excludes all data

Solutions:

Install QtChart: pip install PyQt5.QtChart
Select different date range
Clear artist filter
Check transaction table has data

Commission Calculation Wrong

Verify:

Commission percentage in artist settings
Session commission_override value
Transaction amount is correct
Calculation: amount × pct ÷ 100

Common mistakes:

Using whole number instead of percentage (40 vs 0.40)
Forgetting to divide by 100
Applying commission to net instead of gross

Get Started

Core Features

User Roles

Guides

Overview

Core Concepts

Transaction Model

Multiple Transactions Per Session

Reports Page

Time Period Selection

Filters

Transaction Table

Revenue Chart

Total Revenue Display

Payment Processing

Recording a Payment

Commission Calculation

Export Functionality

Export Dialog

CSV Format

Export Permissions

Auto-Refresh

Financial Dashboards

Key Performance Indicators (KPIs)

Trend Analysis

Best Practices

Technical Details

Database Indexes

Transaction Timestamps

Soft Delete Implementation

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Features

User Roles

Guides

​Overview

​Core Concepts

​Transaction Model

​Multiple Transactions Per Session

​Reports Page

​Time Period Selection

​Filters

​Transaction Table

​Revenue Chart

​Total Revenue Display

​Payment Processing

​Recording a Payment

​Commission Calculation

​Export Functionality

​Export Dialog

​CSV Format

​Export Permissions

​Auto-Refresh

​Financial Dashboards

​Key Performance Indicators (KPIs)

​Trend Analysis

​Best Practices

​Related Features

​Technical Details

​Database Indexes

​Transaction Timestamps

​Soft Delete Implementation

​Troubleshooting

Build docs developers (and LLMs) love

Overview

Core Concepts

Transaction Model

Multiple Transactions Per Session

Reports Page

Time Period Selection

Filters

Transaction Table

Revenue Chart

Total Revenue Display

Payment Processing

Recording a Payment

Commission Calculation

Export Functionality

Export Dialog

CSV Format

Export Permissions

Auto-Refresh

Financial Dashboards

Key Performance Indicators (KPIs)

Trend Analysis

Best Practices

Related Features

Technical Details

Database Indexes

Transaction Timestamps

Soft Delete Implementation

Troubleshooting