Implementation Plan & Status¶
Document 13 | Version: 1.0.0 | Date: April 2026 | Status: Active
This document defines the phased build-out of Thinklio from initial infrastructure through to production readiness, captures the implementation status as of March 2026, and records the monorepo migration that consolidated the codebase into a single repository.
The implementation plan (section 2) describes seven phases from foundation to production hardening, each with objectives, tasks, and success criteria. The implementation summary (section 3) records the substantial work completed during the March 2026 session, including the Supabase migration, the organisation-to-account rename, core data structures, the predictive planning system, and API expansion. The monorepo migration (section 4) documents the consolidation of three GitHub repositories into one.
For the product requirements being implemented, see 01 Product & Strategy. For the system architecture, see 02 System Architecture. For the agent architecture, see 03 Agent Architecture & Extensibility. For the API surfaces, see 09 External API & Tool Integration.
Table of Contents
- Constraints
- Implementation Phases
- Implementation Summary: March 2026
- Monorepo Migration
- Risk Management
- Definition of Done
- Future Phases
- Revision History
1. Constraints¶
Developer. One senior developer (part-time, working around other commitments), with AI-assisted tooling.
Infrastructure. Single Hetzner Cloud VPS (Ubuntu 24.04), managed via Coolify. Expandable to multi-VPS.
Backend. Migrating from Go services to Convex (TypeScript server functions, reactive database, durable workflows). See 02 System Architecture.
No timeline dates. Phases are sequential, not calendar-bound. Each phase completes when its success criteria are met.
Priority. Working software over comprehensive documentation. Ship the simplest thing that works at each milestone, then iterate.
2. Implementation Phases¶
Legacy phase plan. The phase descriptions below were written against the Go + Supabase + Redis stack and describe pre-Convex-era infrastructure (VPS, Redis, pgvector). They are preserved here because the product capability goals per phase (one agent end-to-end, knowledge and tools, multi-tenancy, jobs and composition, three API surfaces, production hardening) carry forward unchanged into the Convex-first rebuild. The current build sequence lives in 02 System Architecture section 18 (implementation plan). Infrastructure-flavoured bullets below (VPS, Redis, Coolify, Go service wiring) are archival; the capability outcomes are current.
Phase Overview¶
| Phase | Focus | Outcome |
|---|---|---|
| 0 | Foundation | VPS provisioned, monorepo scaffolded, database and Redis running, CI basics |
| 1 | Single Agent | One agent, one user, one channel (Telegram). Harness working. End-to-end message to response. |
| 2 | Knowledge and Tools | Knowledge extraction and retrieval. Tool system with policy. Four-layer knowledge model. |
| 3 | Multi-Tenancy | Multiple users, teams, accounts. Assignments, scoping, budget enforcement. |
| 4 | Jobs and Composition | Job system, agent-as-tool delegation, Agent Studio, deferred execution. |
| 5 | API and Channels | Three API surfaces. Additional channels. Agent management. |
| 6 | Production Hardening | Monitoring, alerting, backup, security hardening, performance tuning. |
Phase 0: Foundation¶
Objective. Set up the development and deployment infrastructure. Get a running monorepo with database, cache, and a deployable skeleton.
Tasks.
Infrastructure: provision VPS on Hetzner (CPX31 or similar: 4 vCPU, 8GB RAM, 160GB); harden VPS (SSH on 2222, fail2ban, UFW, non-root user); set up Coolify for deployment management; configure DNS for thinklio domain.
Repository: create monorepo structure (cmd/, internal/, pkg/, migrations/, deploy/, apps/web/, apps/mobile/, docs/); set up linting and testing framework; create Dockerfile templates for each service; create docker-compose.yml for local development.
Data layer: deploy database; deploy Redis 7; create initial migration (minimum viable schema); verify pgvector extension available; set up automated database backups to Cloudflare R2.
Skeleton services: Gateway accepts HTTP requests and returns health check; Agent subscribes to event bus and logs received events; verify service-to-service communication via Redis Streams; health check endpoints on all services.
Success criteria. VPS accessible and hardened. Monorepo builds and deploys via Coolify. Database and Redis running with data persisted across restarts. All skeleton services start, pass health checks, and communicate via events. Local development works with docker compose up.
Phase 1: Single Agent¶
Objective. A single agent that receives a message via Telegram, thinks about it (LLM call), and responds. The harness tracks every step with durability and cost recording.
Tasks.
Gateway and Telegram: implement Telegram channel adapter (long polling or webhook); map Telegram user ID to platform user (seed one user); normalise Telegram messages into universal events; publish message.received events; subscribe to message.response events and deliver via Telegram.
Harness: implement step state machine (created, running, success, failed); implement interaction lifecycle (create, derive state from steps); implement step persistence (write to database before and after execution); implement crash recovery (find incomplete interactions on startup, resume); implement execution mode field on steps (immediate only at this phase).
Agent service: subscribe to message.received events; create interaction and steps; execute harness: context, think, respond (no tools yet); LLM integration via OpenRouter (or direct Anthropic API); publish message.response event.
Context service (minimal): return agent system prompt plus recent chat history; session management (group messages into chats); basic chat history retrieval.
Cost tracking: record token usage per LLM call; calculate cost per step; aggregate per interaction; store in step and interaction records.
Database: add interaction, step, and session tables to schema; seed one agent, one user.
Success criteria. Send a Telegram message and receive an AI-generated response. Every interaction has a complete step record in the database. Steps correctly transition through created, running, success, or failed. Costs are recorded per step and aggregated per interaction. After a forced service restart, incomplete interactions are recovered. Chat history maintained within a session.
Phase 2: Knowledge and Tools¶
Objective. The agent can extract and use knowledge from chats. The agent can use tools with policy enforcement. The four-layer knowledge model is operational.
Tasks.
Knowledge extraction: queue-based async extraction after each interaction; LLM-based fact extraction (subject, predicate, value triples); scope classification (is this user-private or team-shared?); store in knowledge_fact table; generate embeddings for semantic search.
Knowledge retrieval: vector similarity search for relevant facts; keyword-based fallback search; token-budgeted context injection (fit facts within model limits); layer precedence: account, agent, team, user.
Tool system: tool registry (database-driven definitions); policy engine (trust level evaluation); internal tool execution (start with 2 to 3 basic tools: web search, todo management); external tool execution via webhooks (n8n integration); harness integration: think, act, observe loop (interactive mode).
Queue service: background task processing for knowledge extraction; summarisation tasks (session summaries); retry with exponential backoff; dead letter queue for failed tasks.
Knowledge layers: agent knowledge loaded from agent configuration; user knowledge extracted from chats, private to user; team knowledge classified as team-relevant facts from chats; account knowledge as admin-curated facts (manual entry for now).
Success criteria. After several chats, the agent recalls personal facts about the user. Knowledge facts are correctly scoped (user-private facts not leaked). Agent can use tools (for example, search the web) with results in response. Policy engine blocks tools when trust level is insufficient. Background extraction runs reliably without blocking responses. Vector search returns relevant facts for new queries.
Phase 3: Multi-Tenancy¶
Objective. Multiple users, teams, and accounts. Agent assignments with isolated knowledge. Budget enforcement at account, team, and user levels.
Tasks.
User management: user registration (email-based); user authentication via Clerk; user profiles and settings.
Account and team: account creation and management; team creation within accounts; member invitations and role assignment; account policies (tool restrictions, content rules, cost limits, delegation limits).
Agent assignments: assign agents to users, teams, and accounts; knowledge scoping per assignment; multiple agents per team; agent templates for quick creation; per-assignment tool restrictions (narrowing only).
Knowledge isolation: RLS policies enforcing scope-based access; cross-team isolation validation; user knowledge portability (follows user on team leave).
Budget enforcement: budget limits at account, team, and user levels; pre-execution budget checks in the harness; budget warning events at configurable thresholds; budget period management (monthly reset).
Usage service: cost aggregation by user, team, account, and agent; usage reporting endpoints; budget status queries.
Success criteria. Multiple users can interact with agents independently. User A's knowledge is invisible to User B. Team knowledge shared among team members only. Account policies enforced across all account agents. Budget limits prevent over-spending. Usage is correctly attributed to the right user, team, and account. A new user can be onboarded (invited, added to team, interacts with agent). Per-assignment tool restrictions narrow agent capabilities correctly.
Phase 4: Jobs and Composition¶
Objective. Job system for deferred and long-running work. Agent-as-tool delegation. Agent Studio for composition.
Tasks.
Job system: Job, Subjob, and JobObserver entities; job state machine: pending, dispatched, in_progress, resolved, failed, cancelled, timed_out; subjob tracking and progress; usefulness rule evaluation (any_completed_subjob); observer registration and notification via event bus; job timeout monitor; job cancellation (user, agent, and system initiated); flush terminal jobs to durable storage.
Deferred execution: deferred mode for act steps (dispatch and succeed on dispatch); job creation from deferred act steps; follow-up interaction trigger from job.state_changed events; context assembly including job results and context_bundle; n8n integration for external workflow dispatch.
Agent-as-tool delegation: agent tool type in tool registry; invocation contracts (parameter_schema, return_schema); child interaction creation for delegate agents; delegation chain tracking (parent_interaction_id, delegation_depth); cost rollup through delegation chain; immediate and deferred delegation modes.
Delegation governance: delegation depth limit enforcement (account policy: max_delegation_depth); cycle detection at configuration time and runtime; assignment-level restriction evaluation for delegations.
Agent Studio (minimal): admin dashboard section for agent composition; attach agent-as-tool delegations with per-delegation restrictions; delegation graph visualisation (show cycles, depth); composed agent templates.
Success criteria. Agent can dispatch deferred work and receive results via follow-up interaction. Jobs track subjob progress and notify observers at appropriate state changes. Partial output notification works (observer notified when useful output becomes available). Agent A can delegate to Agent B as a tool, with correct cost rollup and audit trail. Delegation depth limit prevents excessive chaining. Cycle detection prevents A to B to A delegation at configuration and runtime. Per-assignment tool restrictions correctly narrow delegate agent capabilities. Job cancellation and timeout work correctly. Agent Studio allows composing agents with visual delegation graph.
Phase 5: API and Channels¶
Objective. Three external API surfaces. Additional channel support. Self-service agent and job management.
Tasks.
Channel API: HTTP/API channel adapter in the gateway; conversational access via API (send message, get response, session management); same governance as native channels.
Platform API: RESTful API per contracts in 09 External API & Tool Integration; agent lifecycle management (create, configure, pause, resume, archive); job dispatch and observation via API (create job, register webhook observer, query status); knowledge management (add, query, bulk import, export); usage and reporting endpoints; API key management (create, revoke, scope); rate limiting on API endpoints; webhook delivery service for job and event notifications; API documentation (auto-generated from code).
Integration API: dynamic tool registration with governance approval; tool execution contract enforcement; event subscription with webhook delivery; external tool health monitoring.
Additional channels: web chat widget (embeddable); channel capability negotiation.
Agent management UI (API-driven): create, edit, and delete agents; configure tools and permissions; manage team assignments; view usage and costs; Agent Studio enhancements.
Success criteria. Channel API fully functional (send messages, get responses, maintain sessions). Platform API fully functional per contract spec. Jobs can be dispatched and observed via Platform API with webhook callbacks. Integration API supports dynamic tool registration with approval workflow. API keys can be created, scoped, and revoked. At least three channels working (Telegram plus Channel API plus web chat). Agents can be created and configured via API. Webhook delivery reliable with retry.
Phase 6: Production Hardening¶
Objective. The system is reliable, observable, secure, and ready for broader use beyond the founding team.
Tasks.
Monitoring and alerting: Prometheus metrics collection from all services; Grafana dashboards (system overview, per-service, per-agent, job system health); alert rules (service down, high error rate, queue backlog, budget exceeded, job timeout rate); notification delivery (email or Telegram).
Security hardening: full input validation audit across all three API surfaces; rate limiting tuning based on real usage; secret management review; container security (non-root, minimal images, no unnecessary packages); network segmentation verification; dependency vulnerability scanning; external tool security review.
Reliability: automated database backups with verified restore; service restart policies; graceful shutdown handling in all services (including in-flight job notifications); chaos testing (kill services, verify recovery, verify job system resilience).
Performance: load testing with realistic traffic patterns (including deferred work and delegation chains); query optimisation based on slow query log; cache tuning based on hit rate metrics; connection pool tuning.
Documentation: operational runbook; incident response procedures; user guide updated to current state; architecture documentation verified against implementation.
Success criteria. All services have health checks, metrics, and log aggregation. Alerts fire within 1 minute of an issue. System recovers from any single service failure. Backup restore tested successfully. Load tested to 10x expected initial usage. Security audit completed with no critical findings. Operational runbook covers all common scenarios including job system operations.
3. Implementation Summary: March 2026¶
Pre-pivot snapshot. This section is a historical record of the implementation state as at late March 2026. Its contents (Supabase migration, Go packages, the original table count, the single Go binary architecture) describe the Go + Supabase + Redis stack that was superseded by the Convex-first rebuild recorded as ADR-017 in the decision log. The current architecture and implementation status are described in section 2 (Implementation Phases) above and in 02 System Architecture section 2 and section 18. Do not take this section as current design guidance; it is retained because the data model, API surface, and governance work done in this session all carry forward conceptually into the Convex era.
This section summarises all changes made during the March 2026 implementation session. The session migrated Thinklio from self-hosted PostgreSQL to Supabase Cloud, renamed "organisation" to "account" throughout the platform, implemented core data structures (tasks, contacts, items, notes), added the predictive planning system, built the unified capability model, and expanded the API surface significantly. The codebase moved from roughly 25 tables and 4 service binaries to 63 tables in a single unified Go binary with 29 internal packages.
3.1 Supabase Migration¶
The platform migrated from self-hosted PostgreSQL (managed via Docker Compose) to Supabase Cloud (project hgskardtwiilauezgoum, Frankfurt region).
Database. Self-hosted PostgreSQL replaced by Supabase Cloud managed PostgreSQL with pgvector, row-level security, Vault, and Realtime.
Authentication. Custom bcrypt plus JWT auth replaced by Supabase Auth. User registration and login endpoints removed from the Go codebase. JWT validation now uses Supabase JWT secret.
Naming. organisation renamed to account throughout the entire codebase and schema. org_id became account_id, org_users became account_user, and so on.
Table naming. All tables use singular names (for example, user_profile, account, team, agent) instead of the previous plural convention.
Credentials. Supabase Vault used for all credential storage (OAuth tokens, API keys, webhook secrets) instead of application-level encrypted storage.
Schema management. Old migrations/ directory (9 migration files) replaced by Supabase-managed migrations.
Docker Compose. PostgreSQL service removed. Only Redis remains as a local service.
Connection. Go services connect via Supavisor pooler using SUPABASE_DB_URL instead of POSTGRES_URL.
3.2 Schema Summary¶
All 63 tables in the public schema, grouped by domain:
Core (identity and tenancy). user_profile (platform users, synced from auth.users via trigger), account (accounts, the tenancy boundary), account_user (account membership with role: owner, admin, editor, viewer), team (teams within an account), team_member (team membership with role), invitation (account and team invitations with token and expiry).
Agents. agent (agent definitions: name, model, system prompt, config), agent_assignment (agent-to-context assignments: account, team, or user scope), agent_template (reusable agent templates for one-click creation), agent_tool (agent-to-tool assignments with per-assignment config), agent_library (agent-to-library assignments for knowledge access), agent_channel (agent-to-channel assignments: which agents respond on which channels).
Execution. session (chat sessions between users and agents), interaction (tracked units of work within a session), step (individual execution steps within an interaction), event (immutable event log, event-sourced core), delivery (message delivery status tracking).
Knowledge. knowledge_fact (structured knowledge facts with scope: subject, predicate, value), library (knowledge libraries: curated collections of documents), library_item (documents within a library).
Media and storage. media (uploaded files and media with polymorphic linking via linked_type and linked_id), storage_bucket (R2 bucket configurations: platform-shared, enterprise-dedicated, account-supplied), account_storage_bucket (account-to-bucket assignments), media_processor (available media processing engines: PDF extract, image OCR, and so on), media_processing_rule (rules mapping file types to processors), media_processing_job (async media processing job queue).
Planning. canonical_plan (reusable plan definitions for agent reasoning), execution_outcome (recorded outcomes of plan executions: success or failure, cost, duration), plan_score (Bayesian scores for plan effectiveness per context).
Platform services. platform_service (external service registry: OpenRouter, Anthropic, Postmark, and so on), llm_model (available LLM models with pricing and capability metadata), account_service_config (account-level service configuration overrides), account_llm_preference (account-level LLM model preferences), credit_ledger (credit transaction log for billing), platform_config (global platform configuration, singleton).
Core data structures. task_list (named groups of tasks), task (individual tasks with status, priority, due dates, recurrence), task_type (task categorisation: system-reserved plus account-custom), contact (people and organisations), contact_interaction (interaction log for contacts), item (externally-initiated requests and tickets), item_type (item categorisation: system-reserved plus account-custom), note (freeform notes with markdown, linking, sharing, and mentions), note_type (note categorisation: system-reserved plus account-custom), note_share (granular note sharing at user or team level), note_mention (at-mention tracking within notes), tag (cross-cutting tags), entity_tag (polymorphic tag-to-entity join).
Channels. channel_config (channel type configurations: Telegram bot tokens, email config, and so on), user_channel (user-to-channel identity links with verification status).
Communications. user_comm (outbound notification dispatch queue: reminders, mentions, assignments), notification (in-app notification records), quality_rating (user feedback ratings on agent responses).
Security and integration. tool (tool registry, 25 seeded tools), api_key (API keys for programmatic access), oauth_token (OAuth tokens for external service integrations), webhook_subscription (webhook subscription configurations), budget_limit (budget limits per scope: account, team, or user), usage_record (resource consumption records per step and interaction).
Jobs. job (deferred work units), subjob (discrete pieces of work within a job), job_observer (job completion notification subscriptions).
3.3 Key Architectural Decisions¶
Four-tier role model. Account membership uses four roles: owner, admin, editor, viewer. This replaces the previous owner, admin, member model. Editor has write access to data but cannot manage account settings or members. Viewer has read-only access.
Unified capability model. Tools and agents share one manifest format and one execution contract. From the harness perspective, invoking a tool and delegating to an agent are the same operation. This eliminates special-casing and simplifies composition.
Multi-bot channel architecture. Each account can have multiple bots per channel type. Agents are assigned to specific channel configs via agent_channel. A single Telegram bot can route to different agents based on context, or an account can run separate bots for different purposes.
Vault for all credentials. All external service credentials (OAuth tokens, API keys, webhook secrets) are stored in Supabase Vault with encrypted-at-rest storage. Application code retrieves credentials at runtime through Vault access, never storing them in application memory longer than needed.
Single binary deployment. All logical services run in a single Go binary during early development for rapid iteration. The architecture is designed for service separation (communication via Redis event bus, not in-process calls), so splitting into separate binaries for general release requires no architectural changes.
Predictive planning system. The platform collects execution outcomes and scores plans using Bayesian methods. Tables: canonical_plan, execution_outcome, plan_score. See 08 Agents Catalogue & Platform Services for the full specification.
User communications queue. Outbound notifications (task reminders, mention alerts, assignment notifications) flow through the user_comm table and are dispatched by a background worker. This decouples notification generation from delivery, supports multiple delivery channels (email, push, in-app, Telegram), and provides retry logic.
Type system pattern. Tasks, items, and notes all follow the same extensibility pattern: a *_type table with system-reserved types (seeded by the platform, immutable) and account-custom types (created by admins). This provides consistent categorisation without schema changes.
3.4 Go Packages¶
All 29 packages live under internal/:
| Package | Description |
|---|---|
admin |
Platform administration handlers |
api |
HTTP API handlers for all endpoint groups |
auth |
Supabase JWT validation and API key auth |
channel |
Channel configuration and routing |
comms |
User communications worker and reminder generation |
config |
Application configuration from environment |
database |
PostgreSQL connection pool (Supabase via Supavisor) |
delegation |
Agent-to-agent delegation logic and cycle detection |
documents |
Document upload, chunking, extraction pipeline |
email |
Postmark email integration (inbound and outbound) |
event |
Redis Streams event bus |
feedback |
Quality rating storage |
harness |
Durable execution harness (step lifecycle, deferred execution) |
health |
Health check endpoint |
integrations/calendar |
Google Calendar integration |
integrations/crm |
HubSpot CRM integration |
integrations/email |
Gmail integration |
integrations/tasks |
Todoist task integration |
integrations/tavily |
Tavily web search integration |
integrations/web |
Web page reader and scraper |
jobs |
Job system (deferred work, subjobs, observers) |
knowledge |
Knowledge fact storage, extraction, and retrieval |
llm |
LLM client (Anthropic, OpenRouter), embedder |
notification |
In-app notification storage |
oauth |
OAuth token storage and refresh |
planning |
Predictive planning (scorer, engine, collector, adapter) |
platform |
Platform services, credits, middleware, health checks |
storage |
S3-compatible storage client (Cloudflare R2) |
telegram |
Telegram bot adapter and manager |
templates |
Agent template storage, instantiation, seeding |
tenant |
Tenant resolution and context |
tools |
Tool registry, executor, policy engine, agent handler |
usage |
Usage metering and budget enforcement |
webhooks |
Webhook dispatch and subscription storage |
4. Monorepo Migration¶
4.1 Problem¶
Thinklio's codebase was spread across multiple GitHub repositories:
| Repo | Contents | Language |
|---|---|---|
schox/thinklio |
Backend API server, Go binary | Go |
schox/thinklio-app |
Web application (React/Next.js) | TypeScript |
schox/thinklio-docs |
Product documentation | Markdown |
schox/thinklio-client |
Original client app (archived, merged into thinklio-app) | TypeScript |
schox/thinklio-admin |
Original admin app (archived, merged into thinklio-app) | TypeScript |
The thinklio-docs repo was included as a git submodule in both thinklio and thinklio-app.
Pain points. The docs submodule required manual sync (git submodule update --remote), created detached HEAD states that needed recovery, and caused deployment failures when Coolify's auth token did not propagate to the submodule URL. Backend API changes and frontend API consumption were in separate repos, requiring multiple commits, PRs, and deployment cycles to ship a cross-cutting feature. The docs submodule pointing to a specific commit meant each consuming repo could be on a different docs version, requiring three repos touched for one doc change. A Flutter mobile app would have added a fourth project, compounding the coordination overhead.
4.2 Solution¶
Merge thinklio-app into thinklio as a subdirectory. The thinklio repo becomes the single monorepo for all product code. The docs become a regular directory (no submodule). An empty Flutter project directory is created for future use.
Target structure:
thinklio/
+-- cmd/ Go entry points
+-- internal/ Go packages (29 packages)
+-- pkg/ Public Go types
+-- apps/
| +-- web/ thinklio-app merged here
| +-- mobile/ empty Flutter project (future)
+-- docs/ thinklio-docs merged here (no submodule)
| +-- product/
+-- deploy/ deployment configs
+-- tests/ integration and E2E tests
+-- go.mod
+-- CLAUDE.md
What changed:
| Aspect | Before | After |
|---|---|---|
| Docs | Submodule in both repos | Regular directory in one repo |
| Web app | Separate repo (thinklio-app) | apps/web/ subdirectory |
| Flutter app | Did not exist yet | apps/mobile/ empty project |
| Backend | Root of thinklio repo | Stays at root (Go code unchanged) |
| Deployments | Coolify points to separate repos | Coolify points to subdirectories in one repo |
| Cross-repo features | Multiple PRs across repos | Single PR, single commit |
| Git history | Separate per repo | Merged, all history preserved |
What did not change. The Go code structure stays exactly where it is (cmd/, internal/, pkg/, go.mod). The Next.js code's internal structure is identical, just nested under apps/web/. Each app deploys independently. Each project keeps its own dependency management (go.mod, package.json, pubspec.yaml).
4.3 Implementation Steps¶
Step 1: Prepare the thinklio repo. Remove the docs submodule (git submodule deinit, git rm), delete .gitmodules, create apps/web and apps/mobile directories.
Step 2: Merge thinklio-docs. Add thinklio-docs as a remote, merge with subtree strategy into docs/ preserving full history, then remove the remote. git log docs/product/ shows all previous doc commits.
Step 3: Merge thinklio-app. Add thinklio-app as a remote, merge with subtree strategy into apps/web/ preserving full history, then remove the remote.
Step 4: Clean up. Remove redundant submodule references and duplicate docs/ directory from the merged web app. Update path references.
Step 5: Update CLAUDE.md files. Root CLAUDE.md references the full monorepo structure. apps/web/CLAUDE.md references docs at ../../docs/product/.
Step 6: Deployment configuration. Create deploy/Dockerfile.web for the Next.js app (multi-stage: deps, builder, runner on node:22-alpine). Update Coolify configuration: API service uses the existing Go Dockerfile, web app service uses the new Dockerfile.web, both point to the same repo but deploy independently.
Step 7: Flutter skeleton. Create minimal Flutter project in apps/mobile/ with pubspec.yaml and placeholder lib/main.dart.
Step 8: Update Makefile. Add web app targets (web-dev, web-build, web-typecheck).
Step 9: Verify and archive. Push to main, verify both Coolify deployments work, verify git history preserved across all subdirectories. Archive schox/thinklio-app, schox/thinklio-docs, schox/thinklio-client, and schox/thinklio-admin on GitHub as read-only references.
4.4 Risks and Mitigations¶
| Risk | Mitigation |
|---|---|
| Git history loss during merge | Use git subtree merge strategy which preserves full history |
| Coolify deployment breaks | Test with a staging deployment first. Keep old repos unarchived until verified. |
| Go build path changes | Go code stays at repo root: no path changes needed |
| Next.js build context | Dockerfile.web explicitly copies from apps/web/ |
| Large repo size | Combined repos are modest. Well under 1GB |
| CI/CD pipeline changes | Coolify watches for changes in specific paths: configure per-service triggers |
4.5 Post-Migration Development Workflow¶
Daily development. All work happens in a single repository. Backend changes in internal/, web app changes in apps/web/, documentation changes in docs/product/. Everything commits together.
Cross-cutting features. A feature that adds a new API endpoint and consumes it in the web app: one branch, one PR, one review, one merge.
Deployment. Coolify deploys each service independently based on which files changed. Changes in cmd/, internal/, pkg/, or go.mod trigger API deployment. Changes in apps/web/ trigger web app deployment. Changes in docs/ trigger no deployment. Changes across both trigger both deployments.
Estimated effort. The entire migration can be completed in a single session (roughly 90 minutes) with zero downtime.
5. Risk Management¶
| Risk | Impact | Mitigation |
|---|---|---|
| LLM provider instability | Agent responses fail | Multi-provider abstraction, fallback models |
| Scope creep | Phases drag out | Strict success criteria, ship minimum viable |
| Knowledge extraction quality | Poor fact quality | Iterative improvement, confidence scoring, human review |
| Cost overruns from LLM calls | Budget exceeded | Pre-execution checks, conservative defaults |
| Single developer bottleneck | Progress stalls | AI-assisted development, modular architecture |
| VPS failure | Total outage | Automated backups, documented recovery procedure |
| Job system complexity | Phase 4 drags | Keep initial usefulness rules simple, defer custom rules |
| Delegation chain bugs | Data leakage, cost explosion | Strict depth limits, fail-closed cycle detection, comprehensive tests |
| External tool reliability | Agent interactions fail | Circuit breakers, health monitoring, graceful degradation |
6. Definition of Done¶
For any phase to be considered complete: all success criteria met; existing functionality from previous phases still works (regression); new code has tests (unit tests for business logic, integration tests for service interactions); documentation updated to reflect current state; deployed and running; changelog updated.
7. Future Phases¶
These are on the roadmap but not yet detailed. They layer on top of the Convex-first phases described in 02 System Architecture section 18.
Agent learning. Workflow codification, pattern recognition, capability level progression. Builds on the predictive planning data captured today (see 08 Agents Catalogue & Platform Services section 3).
Voice and video channels. Audio transcription, voice responses, video interaction. Voice is a likely first candidate for a dedicated Go service (Tier 3 promotion per 02 System Architecture section 12) because real-time streams fit badly in the Convex action model.
Multi-agent collaboration. Agents that coordinate beyond delegation (peer-to-peer).
Marketplace. Shareable agent templates, tool integrations, composed agent blueprints.
Advanced analytics. Usage insights, knowledge graph visualisation, delegation chain analysis. Fed by the Fivetran CDC stream described in 05 Persistence, Storage & Ingestion section 17.
Multi-region deployment. Geographic distribution for latency and compliance.
White-labelling. Custom branding for service providers.
Billing integration. Payment processing via Paddle, plan management, invoicing.
Tier 3 Go services, if warranted. Dedicated Go services for specific runtime domains (channel ingress at high volume, external API surface under load, voice streaming) taken only when analytics show Convex HTTP actions or Workflow slots are the binding constraint. Not a default roadmap item.
8. Revision History¶
| Version | Date | Description |
|---|---|---|
| 1.0.0 | April 2026 | Consolidated from old docs 10 (Implementation Plan v02), 34 (Implementation Summary March 2026 v01), and 39 (Monorepo Migration Plan v01). |