Daily Planning

Note on language: the interface ships in Brazilian Portuguese (pt-BR), with an English translation in progress. The screenshots below reflect the current UI.

---

Why it exists

Most task managers tell you what to do. Few tell you where your day actually went.

Planner is built around one loop: estimate → execute → log → review. You plan the day with time estimates, start a timer when you begin, and the worklog is pushed to Jira automatically. At the end of the month, the metrics page shows the gap between what you thought things would take and what they actually took.

It also carries a second job: tracking recurring maintenance checklists across client projects, so nothing silently rots.

---

Features

Daily board	Plan the day with per-task time estimates, drag to reorder, filter by open/done. Keyboard-driven (N for a new task, arrows to change days, space to pause).
Live timer	One task runs at a time. Start, pause, resume — the elapsed time is what gets logged, not the estimate.
Jira sync	Tasks map to Jira issues and the time spent is pushed as a worklog. Failed pushes are retried, not lost.
Metrics	Hours per day against your goal, time split by category, and an estimate-accuracy view comparing planned vs. actual. Exports to PDF.
Calendar	Week and month views of your workload, showing which days are already full before you commit to more.
Project compliance	A map of client projects and the maintenance steps each one needs (backups, core/plugin updates, PageSpeed checks). Every step is working, broken or pending, with the failure propagating visually to the project.
Google Calendar	Pull in events so meetings count against the day's capacity.
Claude Code (MCP)	Manage the whole thing from your terminal in natural language. See Claude Code integration.
Auth	Email/password plus GitHub and Google OAuth.

---

Screenshots

Metrics — where the month actually went	Calendar — workload before you commit
Project compliance map	Sign in

---

Tech stack

Backend — Laravel 12, PHP 8.2+, MySQL 8, Valkey (Redis-compatible), Sanctum for API tokens, Socialite for OAuth, laravel/mcp for the MCP server.

Frontend — Vue 3 with Inertia.js 2, TypeScript, Vite, Tailwind CSS, Wayfinder for typed route helpers.

Testing — PHPUnit for unit and feature tests, Laravel Dusk (Selenium) for browser tests.

Environment — Docker via Laravel Sail; Mailpit and phpMyAdmin included.

The codebase follows a controller → service → repository layering: controllers stay thin, services hold business rules, repositories own the queries.

---

Getting started

Requirements

• Docker
• Composer
• Node.js 22+

Setup

git clone [email protected]:jeffersonrucu/planner.git
cd planner

cp .env.example .env
composer install
./vendor/bin/sail up -d
./vendor/bin/sail artisan key:generate
./vendor/bin/sail artisan migrate --seed

npm ci
npm run dev

The app is served at http://localhost (or the port set in APP_PORT). Supporting services: Mailpit at :8025, phpMyAdmin at :8080.

Everyday commands

Command	What it does
./vendor/bin/sail up -d	Start the stack
./vendor/bin/sail down	Stop it
./vendor/bin/sail artisan migrate --seed	Rebuild the schema with sample data
./vendor/bin/sail artisan test	Unit and feature tests
./vendor/bin/sail artisan dusk	Browser tests
npm run dev	Vite dev server with HMR
npm run lint / npm run format	ESLint and Prettier

Dependencies are pinned: composer.lock and package-lock.json are committed, and CI installs with composer install / npm ci. Use those rather than update/install when you only mean to reproduce the environment.

---

Configuration

Social login

Both providers are optional — the app works with email and password alone.

GitHub — create an OAuth App at Settings → Developer settings → OAuth Apps with callback http://localhost/auth/github/callback, then set:

GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_REDIRECT_URI="${APP_URL}/auth/github/callback"

Google — create OAuth credentials in the Google Cloud Console and set:

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URI="${APP_URL}/auth/google/callback"

Google Calendar is a separate integration with its own credentials and callback, so signing in and granting calendar access stay independent. Enable the Calendar API on the project and set:

GOOGLE_CLIENT_ID_INTEGRATIONS=
GOOGLE_CLIENT_SECRET_INTEGRATIONS=
GOOGLE_REDIRECT_URI_INTEGRATIONS="${APP_URL}/dashboard/configuracoes/google/callback"

Jira

Jira credentials are entered per user in the app (Settings → Jira), not through .env. You need your Atlassian host, account email and an API token. Tokens are stored encrypted and scoped to the user.

---

Claude Code integration (MCP)

Planner exposes its tasks and metrics as MCP tools, so you can run your day from the terminal:

> list my tasks for today
> create task "review PR #50" with a 1h estimate
> start task 42
> how far am I from today's goal?

Install

# inside Claude Code
/plugin marketplace add github:Studio-STG/personal-planner-plugin
/plugin install personal-planner@personal-planner-marketplace
# then /quit and reopen

The installer asks for your MCP server URL and a bearer token generated at Settings → Claude Code. The token is kept in the system keychain, not in a plain-text file.

Plugin source lives in claude-plugin/ and is published at Studio-STG/personal-planner-plugin.

How it is secured

Layer	Where	Role
Route	routes/ai.php	Mcp::web('/mcp', PlannerServer::class)
Tools	app/Mcp/Tools/	Thin wrappers over TaskService / MetricsService
Auth	Sanctum abilities	Bearer tokens with granular scopes
Isolation	BelongsToUser trait	Global scope forces Auth::id() on every query
Audit	mcp_audit_logs + LogMcpRequest	Every call recorded, parameters masked
Rate limit	AppServiceProvider	60 req/min per token, 300 req/min per IP
Headers	SecureMcpHeaders	HTTPS enforced in production, HSTS, nosniff

Request chain:

SecureMcpHeaders → auth:sanctum → throttle:mcp → LogMcpRequest → tool (RequiresAbility) → Eloquent (BelongsToUser scope)

Available scopes (app/Enums/McpAbility.php): tasks:read, tasks:write, metrics:read, time:log.

tests/Feature/Mcp/McpSecurityTest.php covers the cases that matter: missing token → 401, insufficient scope → 403, cross-user access denied even with a valid ID, revoked token → 401, and audit entries written for every call.

---

Project layout

app/
  Http/Controllers/   thin controllers, one per resource
  Services/           business rules
  Repositories/       database queries
  Mcp/                MCP server, tools and abilities
  Models/Concerns/    shared traits (per-user scoping)
resources/js/
  pages/              Inertia pages
  components/         Vue components
  routes/, actions/   generated by Wayfinder — do not edit by hand
database/migrations/  schema
tests/
  Feature/, Unit/     PHPUnit
  Browser/            Dusk
docs/screenshots/     images used in this README

Core tables

Table	Holds
users, profiles	Accounts and preferences
categories	Task categories
tasks	Tasks, estimates and time spent
logs_tasks	Timer sessions per task
daily_goals	Per-day hour targets for the month
projects, project_steps, project_step_status	Compliance checklists and their state
jira_credentials, google_credentials	Encrypted per-user integration credentials
mcp_audit_logs	MCP call audit trail

---

CI and deployment

Four GitHub Actions workflows run on the repository:

Workflow	Trigger	Does
tests.yml	PR to master/develop	Unit and feature tests
dusk.yml	PR to master/develop	Browser tests against a real Chrome
lint.yml	PR to master/develop	Pint, ESLint and Prettier checks
deploy-prod.yml	push to master	Installs from the lockfiles, builds with Vite, syncs over rsync, then migrates and rebuilds caches on the server

---

Contributing

Issues and pull requests are welcome.

1. Branch off master (git checkout -b feature/my-feature)
2. Commit using Conventional Commits (feat:, fix:, chore:…)
3. Make sure sail artisan test and npm run lint pass
4. Open a pull request describing what changed and why

---

License

MIT © Jefferson Oliveira