# Project pack: solidtime @ 93eb93f

Facts about **solidtime** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> solidtime is a modern time tracker for freelancers and small teams. You start a timer or add entries by hand, tag them to clients and projects, set billable rates, and see reports of where your time went. It can be self-hosted or used as a hosted service, and it has a desktop timer and an API.

## Version and source
- Repository: https://github.com/solidtime-io/solidtime
- Pinned commit: `93eb93f1dc2de0d50849ce7883a601dd76691df1`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/solidtime-io/solidtime/archive/93eb93f1dc2de0d50849ce7883a601dd76691df1.zip
- Official docs: https://docs.solidtime.io
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/solidtime-io/solidtime bespoke-solidtime
  cd bespoke-solidtime
  git checkout --detach 93eb93f1dc2de0d50849ce7883a601dd76691df1
  # Prepare development requirements and local configuration first.
  composer install
  npm install
  cp .env.example .env
  ./vendor/bin/sail up -d
  ./vendor/bin/sail artisan migrate
  npm run dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  Follow the self-hosting guide at https://docs.solidtime.io/self-hosting/intro, which provides a ready-made Docker Compose file.
  ```

- Needs: Docker, or PHP 8.3, Composer, Node 22 and Postgres for development
- Develop: `./vendor/bin/sail up -d && npm run dev`
- Test: `./vendor/bin/sail artisan test`
- Check/lint: `./vendor/bin/pint`
- Stack: php, typescript (Laravel, Inertia.js, Vue, Tailwind). Difficulty for a non-developer with an AI: **moderate**. A standard Laravel and Vue application with an OpenAPI description. Reports, rates and exports are good places to start; the rest is regular Laravel code.

## Customisation points (settings → extend → code)
- **clients-projects-rates** [settings]: Billable rates, who can see what, and your client list. → `Organization settings, Clients, Projects, Members`
- **reports** [settings]: Weekly and monthly summaries, exports as CSV or PDF. → `Reports page, shared report links`
- **api** [extend]: Start and stop timers from scripts and shortcuts. → `openapi.json and Settings → API tokens`
- **report-layouts** [code]: New report types and exports. → `resources/js/Pages and app/Service`
- **models** [code]: New fields such as purchase order numbers or tags. → `app/Models, database/migrations`

## Must keep working
- Laravel migrations. Add new ones; never edit old ones.
- Rate calculations and billable totals.
- Organization membership and role checks.

## Staying updatable
Prefer the API and exports. For code, use new classes and pages and avoid the extensions folder unless you need a plugin.

## Data, costs and safety
- Personal data: **yes**. Stored in: A Postgres database plus a storage folder or bucket. Time entries show what you worked on and for whom. Back up the database regularly.
- Service: Email (SMTP) (optional, usually free to a few dollars): Invitations and password resets.
- Service: Object storage (S3-compatible) (optional, free locally): Report exports and logos.
- Setting `APP_KEY` (**secret**: the person enters it themselves, never in chat): Laravel encryption key. Never paste it into an AI chat.
- Setting `DB_PASSWORD` (**secret**: the person enters it themselves, never in chat): Database password.
- Setting `APP_URL`: The address people use to reach solidtime.
- Keep APP_KEY and database passwords out of Git and chats.
- Time entries reveal client work. Restrict who has an account.

---

# Customising solidtime

solidtime is Laravel on the back end and Vue with Inertia on the front end. If you know either, the structure is familiar.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Pages (dashboard, reports, projects) | resources/js/Pages/ |
| Controllers and API | app/Http/Controllers/ |
| Business logic | app/Service/ |
| Data models | app/Models/ |
| Migrations | database/migrations/ |
| API description | openapi.json |
| Tests | tests/ and e2e/ |

## Use the gentlest change first

1. **Settings (no code):** clients, projects, rates, members and report filters.
2. **Extend:** API tokens and the OpenAPI description.
3. **Code:** new models, services and pages.

## Recipes

- **New report column:** add the data in a service class, return it from the report controller, then show it in the report page.
- **New field on projects:** add a migration, add it to the model and request validation, then add it to the project form.

## Running and checking your changes

- `./vendor/bin/sail artisan test` for PHP tests.
- `npm run lint` and `npm run type-check` for the front end.
- Start a timer, stop it and check the report total.

## Pitfalls

- Rates are money. Add tests when you touch billing code.
- Don't commit `.env`.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/solidtime/93eb93f/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/solidtime/93eb93f/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/solidtime/93eb93f/r2/SKILL.md)