Freelance OS — Dashboard Edition

A desktop app for freelancers to manage clients, projects, time tracking, and invoicing — built with JavaFX and a local SQLite database.

Features

• Dashboard — monthly revenue, active projects, hours tracked, and a revenue trend chart
• Clients — add, edit, and delete client records
• Projects — track project status, assign clients, and set estimated hours with tracked-vs-estimated progress
• Time Tracker — start/stop timer per project, logs entries with task descriptions
• Invoices — generate invoices from unbilled tracked hours, mark as paid, and print (or save as PDF via your OS print dialog)
• Time Inbox — review optional local window-activity suggestions before approving them into billable time
• Project status reports — copy a current Markdown update for a selected project directly to the clipboard
• Pipeline projection — see the estimated unbilled value of active projects on the dashboard

Tech Stack

• Java 25
• JavaFX 17.0.6 (javafx-controls, javafx-fxml)
• AtlantaFX 2.0.1 — PrimerDark/PrimerLight theming
• SQLite (via sqlite-jdbc 3.42.0.0) — local, file-based database, no server required
• Maven — build and dependency management

Prerequisites

• JDK 25 or later
• Maven 3.6+

Running the App

mvn javafx:run

This launches the app via com.said.freelance.Launcher. On first run, it creates a local SQLite database at data/freelance.db and initializes the schema automatically — no manual setup required.

If you ever hit a stale-build error (a class not found immediately after a successful compile), clear the build cache and try again:

mvn clean javafx:run

Building

mvn compile

Compiled classes and resources land in target/.

Project Structure

src/main/java/com/said/freelance/
├── Main.java                  # Application entry point
├── Launcher.java              # Delegates to Main (works around a javafx-maven-plugin quirk)
├── dao/
│   └── DatabaseConnection.java  # SQLite connection + schema initialization
├── model/                     # Client, Project, Invoice, TimeEntry
├── ui/                        # One controller per screen
└── util/
    └── UIUtils.java           # Shared dialog/alert/dropdown helpers

src/main/resources/
├── fxml/                      # One FXML view per screen
├── css/app.css                # App-wide styling (brand accent, dark/light theme support)
├── schema.sql                 # Database schema, run on every startup (idempotent)
└── logo.png                   # App icon / branding

Data

Your data lives in data/freelance.db, a local SQLite file — nothing leaves your machine. This path is excluded from version control (see .gitignore), so each developer's local data stays separate from the repository.

Payment QA

See the Payment Webhook QA Portfolio Report for the localhost-only sandbox architecture and verified reconciliation and idempotency scenarios.

Time Inbox Setup

The Time Inbox is deliberately approval-based: its optional Python tracker creates local time_suggestions only. Nothing reaches time_entries until you select a suggestion in the app and click Approve to Ledger.

1. Copy time-tracker-rules.json.example to config/time-tracker-rules.json and map each window-title fragment to one of your project names.
2. Install the tracker dependency: py -m pip install -r tools/requirements-time-inbox.txt.
3. Start it with py tools/time_inbox_tracker.py, then review suggestions in Time Tracker > Approval Inbox.

The dashboard's pipeline and the copied status reports use hourly.rate from config/freelance.properties. Copy freelance.properties.example to that path and set your rate; the visible fallback is $100/hr.

License

MIT — see LICENSE.