CustomCalc MVP Documentation Pack

Product: CustomCalc — Clockify Custom Field Calculator Add-on
Purpose: Development-ready handoff so an AI coding agent or developer can implement a working MVP with minimal clarification.
Date: 2026-05-14
Primary implementation target: TypeScript add-on/runtime service for Clockify.

What this pack contains

This pack turns the research and SDK/API notes into a practical implementation blueprint:

1. Product requirements and acceptance criteria.
2. Functional and technical specifications.
3. Tech stack recommendation.
4. Runtime architecture and data-flow diagrams.
5. Data model and persistence schema.
6. Formula DSL specification.
7. Clockify API contracts and integration constraints.
8. Security, auth, privacy, and marketplace readiness requirements.
9. MVP implementation plan plus post-MVP roadmap.
10. Testing, deployment, operations, and rollback plans.
11. A single one-shot AI build prompt and AGENTS.md for coding-agent handoff.
12. Machine-readable artifact manifest and task graph.

MVP in one paragraph

CustomCalc is a Clockify add-on/backend service that watches time-entry changes, evaluates administrator-defined formulas using a safe expression DSL, and writes computed values into configured Clockify custom fields. It uses webhooks for fast recalculation, a reconciliation worker for missed events/backfill, a persistent idempotency layer to avoid duplicate writes, and dry-run/rollback controls because the product mutates user-visible business data.

Source inputs used

The pack is based on these project files already provided in the workspace:

• deep-research-report (1).md: product strategy, PRD, architecture, implementation plan, and testing/operations recommendations.
• openapi.yaml: Clockify OpenAPI reference, endpoint paths, auth, rate limiting, pagination, region URL, custom-field, time-entry, webhook, report, and entity-change contracts.
• services.md: SDK service layer, pagination, bulk retry, report, webhook, settings, and workspace helpers.
• auth-and-tokens.md: user token, lifecycle token, webhook signature, RS256 verification, host enforcement, drift detection, and service URL handling.
• canonical-rules.md: Clockify add-on development rules, source precedence, scopes, lifecycle, webhooks, UI, structured settings, persistence, release readiness.
• storage.md: installation stores, idempotency stores, encryption, SQLite/KV/Redis guidance.
• webhook-authenticity.md: required webhook checks and fail-closed behavior.
• webhook-events.md: event/scope matrix.
• api-scope-mapping.md: endpoint-to-scope mapping.
• environments-and-regions.md: region/environment URL rules.
• marketplace-readiness.md and private-addons.md: public/private add-on publishing, privacy, security, and operational responsibilities.
• window-events-and-ui.md: iframe token handling, Clockify postMessage bridge, theme/language handling.

Recommended implementation boundary

The MVP should implement the Clockify runtime service, not a full SaaS platform. It should include a minimal admin configuration path through structured settings or checked-in config, plus an optional local admin API for dry runs and reconciliation. A full marketplace listing, hosted no-code formula builder, billing, multi-region SaaS operations, and a Codex goal-client package should be treated as post-MVP unless they already exist in the target repository.

File map

File	Use
docs/01_PRD.md	Product requirements, users, goals, scope, acceptance criteria.
docs/02_FUNCTIONAL_SPEC.md	Features, flows, edge cases, formula/writeback behavior.
docs/03_TECH_STACK.md	Chosen MVP stack and alternatives.
docs/04_ARCHITECTURE.md	Components, data flow, diagrams, sequence flows.
docs/05_DATA_MODEL.md	Tables, schemas, indexes, state transitions.
docs/06_FORMULA_DSL_SPEC.md	Expression language, types, functions, safety constraints.
docs/07_API_CONTRACTS.md	Clockify and service API contracts.
docs/08_SECURITY_AUTH_PRIVACY.md	Auth, token handling, webhook verification, privacy, abuse controls.
docs/09_IMPLEMENTATION_PLAN.md	MVP work breakdown, dependency order, milestones, estimates.
docs/10_TEST_PLAN.md	Unit, contract, integration, E2E, fault-injection test matrix.
docs/11_DEPLOYMENT_OPERATIONS.md	Local/staging/prod deployment, runbooks, rollback, monitoring.
docs/12_POST_MVP_ROADMAP.md	Post-MVP epics, phased roadmap, scaling plan.
docs/13_AI_ONESHOT_BUILD_PROMPT.md	Copy-paste prompt for an AI coding agent.
docs/14_ADR_AND_RISK_REGISTER.md	Decisions, tradeoffs, risks, mitigations.
docs/15_ACCEPTANCE_CHECKLIST.md	Final “done” checklist for MVP handoff.
AGENTS.md	Coding-agent project rules.
mvp-task-graph.yaml	Machine-readable task graph.
artifact-manifest.json	Generated documentation manifest.

Non-negotiables for the coding agent

• Use TypeScript with strict types.
• Never use eval, new Function, or arbitrary JavaScript execution for formulas.
• Never hardcode Clockify hosts; derive from verified claims or config.
• Verify lifecycle tokens, user tokens, and webhook signatures fail-closed.
• Compare webhook event type headers and stored webhook auth tokens where available.
• Keep webhook handlers fast; enqueue work and return quickly.
• Make every Clockify write idempotent and diff-based.
• Include dry-run mode before live writeback.
• Include tests before marking MVP complete.