Implementation Plans¶

This directory contains comprehensive documentation for all implementation plans in the po-platform project.

#	Plan	Status	Summary
001	PDF Signing Tests	✅ Completed	Comprehensive test suite for PDF signing feature and contracts workflow.
002	Contract Workflow Test Suite	✅ Completed	Comprehensive test suite for partner contract creation workflow.
003	Partner Info Form UX Improvement	✅ Completed	Refactoring of the Partner Info form to improve user experience effectively consolidating fragmented save buttons into a single global save mechanism.
004	Partner Calendar UX Improvement	✅ Completed	Implementation of a comprehensive layered availability system for partners.
005	Service Form UX Refactor	✅ Completed	Comprehensive refactor of the partner console service form.
006	Calendar Form UI Improvements	✅ Completed	Consolidated calendar availability simulation into a single rules-based API endpoint and unified frontend component.
007	Availability Simulator View Enhancements	✅ Completed	Implementation of 9 distinct, purpose-built view layouts for the Availability Simulator (Day, Week, Month, Year).
008	Glassmorphism UI Refinement	✅ Completed	Systematic refinement of the partner-console UI to implement glassmorphism principles.
009	Enhanced Calendar Availability Rules	✅ Completed	Implementation of frequency-specific recurrence controls (weekly, monthly, yearly) for calendar availability rules.
010	Service Calendar Bindings	✅ Completed	Multi-calendar binding support for the service availability tab. Partners can link multiple calendar
011	Calendar Enhancements — Exclude Dates & Capacity	✅ Completed	Adds two new capabilities to the calendar rule model:
012	Calendar Service — Core Implementation	✅ Completed	Documents the fully implemented calendar-service microservice.
013	ICS Export Phase 1	✅ Completed	Implementation of Phase 1 of the external calendar integration (ICS Export).
014	Negative ICS Export (Strategy B)	✅ Completed	Implements the "negative" ICS export strategy for service calendars.
015	ICS Import	✅ Completed	Implements the ICS Import feature, allowing partners to import existing .ics
016	Calendar Exception Refactoring — Atomic Model	✅ Completed	Refactored the calendar_exception data model from range-based
017	Two-Way ICS Sync	✅ Completed	External calendar sync via polling — partners connect ICS feeds, background worker creates exceptions.
018	Activity Log System	✅ Completed	Two-tier extensible activity log system with RabbitMQ publish, WebSocket push, and Activity Center frontend.
019	Architecture Simplification Review	✅ Delivered	Pre-launch inventory of 17 services + 6 infra components with simplification lens. Produced Wave 2 candidate list (Riff `#24`-`#39`); end state if executed: 11 services + 5 infra. Research-only plan; execution in child tickets.
020	Payment Service — MoR + Stripe Connect Express	🟡 Draft	Pre-launch hard gate. Three-rail money flow: customer → platform (regular Stripe), platform → partner (Connect Express + Transfers API), and locally-paid services (no Stripe). PT-market methods + Multibanco + MB WAY. Insurance regulation (IDD) flagged for legal counsel.
021	Experience Service — DAG Orchestrator Build-Out	🟡 Draft	Pre-launch trademark feature. Builds the AI-curated multi-service Experience engine (intent extraction, candidate scoring, DAG planning, external provider integration). Stays separate from ai-service per architecture-review.
022	Strapi UGC Pipeline — Partner Content Publication	🟡 Draft	Pre-launch. Partner content workflow: draft → submit → admin review → approved → published to Strapi → public-fo reads from Strapi. Adds 5 new content types; partner-service joins dbmate.
023	Contract Service — Reverse Migration + Customer Contracts	🟡 Draft	Pre-launch. Reverse-migrate `partner-service.partner-contracts` → contract-service; add customer↔company click-through contract type for booking-time terms acceptance; closes `contract.events` orphan exchange.
024	Booking Flow — frontend checkout + backend persistence	🟢 Ready	Pre-launch hard gate. Closes the gap between Plan #021 candidate Experiences and Plan #020 payment-service backend: `bookings` schema in experience-service, BookingsConsumer for `payment.events`, public-fo BookingSummary/Checkout/Return pages reusing E1-PoC Stripe Elements pattern. All 6 pre-DRAFT decisions resolved 2026-05-06; F1 round 1 reviewed without scope change. Single biggest remaining blocker for Plan #020 going user-facing.
025	Marketplace Completeness (deferred follow-ups from #020 + #024)	🟡 Draft	Stub plan capturing the deferrals from #020 and #024 (multi-partner destination charges, partner-attribution audit, factura emission, DSAR endpoints, etc.). 8 candidate slices; pre-DRAFT decisions still open. Not launch-blocking; sequenced post-Plan-#024 close-out.
026	Test Foundation + Structural Hygiene	🟢 Ready	TDD becomes the default for new code; characterization-test backfill on load-bearing legacy. Phase 1: CI gate + test DB harness + payment-service pilot + zero-test bootstrap (3 weeks). Phase 2: shared `@po/contracts` package + OpenAPI completion + AsyncAPI/Zod consumer validation + service template (4 weeks). Phase 3: risk-ranked legacy backfill (ongoing). Explicitly rejects ORM migration, microservice consolidation, Express→NestJS rewrites pre-launch. All pre-DRAFT decisions resolved 2026-05-10; Riff epic `#96` + 11 per-slice sub-tasks.
027	Self-hosted Mail (Mailcow) with Resend smarthost	🟡 Draft	Hybrid mail design: Mailcow on `srv884655` for inbound + IMAP + webmail + storage; Resend as outbound smarthost (sidesteps Hostinger port-25 block + cold-IP deliverability). Coexists with existing Resend transactional pipeline on `mail.portugalodyssey.pt`. MTA hostname `mx.portugalodyssey.pt`; 12 mailboxes/aliases (personal + public-facing + compliance + apex sender); apex `portugalodyssey.pt` verified as 2nd Resend sending domain so `noreply@portugalodyssey.pt` works. 8 slices A-H, ~7-9 h focused work over 2 days.
028	Web Presence Frontend — brand site with embedded RAG chat	🟡 Draft	Parallel auxiliary track (Riff `#3` in aux tracker `61596011-...`, not canonical `8da0e2bf-...`). Nomenclature ownership confirmed via parallel-session memo. New `frontends/web-presence/` sibling app (Vite+React 19+TS+Tailwind 4) replacing public-fo on the apex; public-fo demoted to `app.portugalodyssey.pt`. Includes from-scratch design system (tokens + 5 glass primitives via the global `/glassmorphism` skill), a generous AI chat textarea wired to ai-service `/api/v1/chat` with scrolling Q&A backdrop, finalised logo + favicon kit, and 5 MJML email templates × EN/PT for notification-service. 10 slices A-J. Branch prefix `feat/plan-028/*` + compose project `po-web-presence`.
031	MkDocs Documentation Site — publish `docs/` as a navigable site	🟢 Ready	Material for MkDocs over `docs/`. IA on two axes: audience tabs (Clients/Developers/DevOps/Reference) + service & frontend categories — the 4 frontends (public-fo, web-presence, partner-console, admin-console) as first-class sections under Developers. Zero-risk allowlist publication (publish only vetted content; fail-closed) + GitLab Pages internal hosting + blocking gitleaks backstop. All 6 open decisions resolved 2026-06-02. 6 slices A–F. Branch prefix `track=docs-site`.

Statistics¶

Metric	Count
Total Plans	28
Completed	19 (#001–#019)
In Progress / Drafted	9 (#020–#028)
Planned	0

Documentation Structure¶

Each plan folder follows a consistent structure:

NNN-plan-name/
├── README.md           # Plan overview and quick links
├── metadata.yaml       # Machine-readable plan metadata
├── artifacts/          # Original planning artifacts
│   ├── implementation_plan.md
│   ├── task.md
│   └── walkthrough.md
├── human/              # Diataxis documentation for humans
│   ├── tutorial.md     # Step-by-step learning guide
│   ├── howto.md        # Task-oriented practical guides
│   ├── reference.md    # Complete technical reference
│   └── explanation.md  # Conceptual understanding
└── ai-agent/           # CSF documentation for AI agents
    ├── tutorial.csf.md
    ├── howto.csf.md
    ├── reference.csf.md
    └── explanation.csf.md

See CONTRIBUTING.md for detailed documentation guidelines.

Tools¶

Update Index¶

To regenerate this README from plan metadata:

./scripts/update-plans-index.sh

Or manually update the tables above when adding/modifying plans.

By Status¶

✅ Completed¶

001-PDF Signing Tests
002-Contract Workflow Test Suite
003-Partner Info Form UX Improvement
004-Partner Calendar UX Improvement
005-Service Form UX Refactor
006-Calendar Form UI Improvements
007-Availability Simulator View Enhancements
008-Glassmorphism UI Refinement
009-Enhanced Calendar Availability Rules
010-Service Calendar Bindings
011-Calendar Enhancements — Exclude Dates & Capacity
012-Calendar Service — Core Implementation
013-ICS Export Phase 1
014-Negative ICS Export (Strategy B)
015-ICS Import
016-Calendar Exception Refactoring — Atomic Model
017-Two-Way ICS Sync
018-Activity Log System

🔄 In Progress¶

None currently

📋 Planned¶