FPDP Development Roadmap and Strategy

1. Purpose

This document turns the FPDP product vision into an executable delivery plan. It defines what should be built first, why that order matters, what each milestone must prove, and which quality gates must be passed before the next phase starts.

This roadmap is based on the repository's state when Phase 0 started, kept here as the planning baseline:

- a lightweight PHP 8.2 modular structure exists;

- a static MVC landing view can be rendered;

- payment and external-content interfaces and factories exist;

- only the dummy payment gateway is functional;

- RSS, Atom, and Custom API adapters can normalize remote records in memory;

- an initial payment and integration schema exists;

- identity/authentication, local post CRUD, the local timeline, post editor, and public profile UI are implemented; most queue, commerce, external-sync, personalization, and federation capabilities are not.

Phase 0 and most of Phase 1 have since been completed. See the development progress report for the current, verified state of every phase and workstream.

2. Strategic outcome

The first meaningful product release must let a node owner complete this journey:

Install node → Create owner account → Complete public profile
→ Publish local post → Connect RSS → Sync and review attributed content
→ View the public personal digital home

Payment, marketplace, and federation should not be placed on the critical path until this ownership-and-content loop is reliable.

3. Development strategy

3.1 Build vertical slices

Deliver small end-to-end capabilities that include route, authorization, validation, service, persistence, response contract, UI where required, and tests. Avoid building every database table first or every UI screen first without an executable journey.

Recommended first slice:

Register → Persist user/node/profile → Authenticate → Read /me

Recommended second slice:

Create local post → Persist → Read public post → Display on profile

3.2 Contract-first API development

Use <code>openapi.yaml</code> as the target API contract.

For each endpoint:

1. confirm its request, response, authorization, and error behavior;

2. add contract tests or request-level tests;

3. implement the smallest service and persistence path;

4. keep the OpenAPI document synchronized with implementation;

5. mark implementation status in release notes or an endpoint matrix.

The contract may be revised when implementation reveals a design problem, but code and documentation must change together.

3.3 Preserve provider boundaries

Business logic must depend on PaymentGatewayInterface and ExternalContentProviderInterface, not concrete adapters. Unknown provider codes must fail explicitly; silently falling back to a dummy or RSS adapter is unsafe for production behavior.

3.4 Establish security boundaries early

Security work is part of each feature, not a final hardening phase. Authentication, authorization, ownership checks, secret encryption, SSRF protection, webhook verification, log sanitization, and idempotency must be implemented with the capability that needs them.

3.5 Keep asynchronous work observable

Feed synchronization and webhook processing need explicit states, retry policy, attempt counts, timestamps, sanitized errors, and operational visibility. A queued capability is incomplete when operators cannot see or recover failed work.

3.6 Use migration-owned persistence

Replace the schema stub with ordered, repeatable migrations. Add foreign keys, unique constraints, indexes, timestamps, and retention rules deliberately. Avoid relying on manually edited production schemas.

3.7 Delay federation until local semantics are stable

Federation amplifies identity, moderation, delivery, trust, and consistency problems. Stabilize local profiles, posts, visibility, canonical URLs, and source attribution before exchanging remote activities.

3.8 Let each node own its appearance and language

A personal digital home should not look identical for every owner. Node-level presentation (theme, layout, custom CSS) and language (default locale, available languages) are owner-controlled settings, not global application config. Store them per node so they survive independently of code deploys, validate custom CSS defensively (see Phase 2 task 8), and always keep a safe built-in theme/locale as the fallback when a setting is missing or invalid.

4. Priority model

| Priority | Meaning | Rule |

|---|---|---|

| P0 | Release blocker | Required for a secure personal-node content loop |

| P1 | MVP completion | Required for reliable external aggregation and operation |

| P2 | Commercial capability | Products, orders, and real payments |

| P3 | Network expansion | Federation and advanced ecosystem capabilities |

Within a priority, complete foundational risks before convenience features. Security and data-integrity tasks inherit the priority of the feature they protect.

5. Delivery roadmap

Phase 0 — Engineering foundation

Objective: create a safe, testable application shell before adding product features.

Expected duration: 1–2 weeks.

Tasks, in order:

1. Add environment configuration with validation and an example file containing no secrets.

2. Add a public front controller and explicit web/API routing.

3. Add centralized JSON responses, exception mapping, request IDs, and sanitized logging.

4. Introduce database connection management and ordered migrations.

5. Convert the existing schema into migrations; add foreign keys and operational indexes.

6. Add automated unit, integration, and HTTP test entry points.

7. Add static analysis, code style checks, and a repeatable CI command.

8. Make factories reject unsupported provider codes instead of silently choosing a fallback.

Exit criteria:

- /api/v1/health returns the documented envelope;

- migrations run on an empty database and can be repeated safely;

- test, lint, and static-analysis commands pass from a clean checkout;

- runtime errors return sanitized responses with request IDs;

- no application secret is committed or printed in logs.

Phase 1 — Identity and personal node

Objective: establish ownership, authentication, and the public profile.

Expected duration: 2–3 weeks.

Tasks, in order:

1. Add nodes, users, profiles, sessions/API tokens, and audit-event migrations.

2. Implement password hashing and secure owner registration.

3. Implement login, logout, token expiration/revocation, and session protection.

4. Add authentication and role/ownership middleware.

5. Implement /auth/register, /auth/login, /auth/logout, and /me.

6. Implement profile update and public-profile read endpoints.

7. Build a minimal profile editor and public profile page.

8. Add rate limiting for authentication endpoints.

Exit criteria:

- one owner can securely create and access a node;

- unauthenticated, owner, and admin permissions are tested;

- profile visibility rules work at API and UI levels;

- credentials and tokens never appear in API output or logs;

- registration-to-public-profile flow passes an end-to-end test.

Phase 2 — Local content and timeline

Objective: make the user's domain useful without any external provider.

Expected duration: 2–3 weeks.

Tasks, in order:

1. Add local post and media metadata migrations.

2. Implement post create, read, update, soft delete, draft, and visibility rules.

3. Generate stable canonical URLs on the user's node.

4. Implement public post and timeline queries with cursor pagination.

5. Build the post editor, post page, and local timeline.

6. Add output escaping, content sanitization, and media validation.

7. Add ownership, visibility, pagination, and soft-delete tests.

8. Add node appearance and language settings: a node_settings migration (theme, layout choice, custom CSS, default locale, enabled languages); a GET/PATCH /me/settings endpoint pair; server-side custom-CSS sanitization (reject @import, expression(), and embedded <script>; cap length) before it is ever rendered back to a visitor; and a settings UI reusing the language/appearance switchers already prototyped in the interactive mockup.

Exit criteria:

- an owner can draft, publish, edit, unpublish, and delete a local post;

- visitors see only content allowed by visibility rules;

- every published item has stable authorship, source metadata, and canonical URL;

- timeline queries remain indexed and paginated;

- an owner can set a theme, layout, custom CSS, and default/available languages for their node, and the public profile and timeline render with those settings applied, falling back safely when a setting is absent or invalid.

Phase 3 — External feed aggregation

Objective: connect external sources safely and display normalized content with attribution.

Expected duration: 3–4 weeks.

Tasks, in order:

1. Add strict connector configuration validation and explicit provider errors.

2. Implement outbound HTTP with DNS/IP checks, SSRF protection, timeouts, size limits, and safe XML handling.

3. Implement source test/preview without persistence.

4. Persist external sources and encrypted credentials.

5. Define the normalized external-post mapping and deterministic deduplication keys.

6. Implement queue claiming, locking, retries with backoff, and dead-letter handling.

7. Persist normalized posts and update sync state atomically.

8. Merge external items into the timeline with provider and canonical-link labels.

9. Implement manual sync, disable, disconnect, and optional imported-content purge.

10. Add an integration-health screen with actionable error states.

Exit criteria:

- RSS, Atom, and Custom API test/preview paths are safe and bounded;

- repeated synchronization does not duplicate posts;

- failed jobs can retry and can be inspected without exposing secrets;

- disconnect behavior and data retention are explicit and tested;

- all external timeline items show source type, provider, author, and canonical URL.

Phase 4 — Operations and MVP hardening

Objective: make the personal content node deployable and supportable.

Expected duration: 2 weeks.

Tasks, in order:

1. Add an admin health dashboard for dependencies, jobs, and recent failures.

2. Add audit events for authentication, source configuration, and administrative actions.

3. Add backup, restore, migration, scheduler, and worker runbooks.

4. Add rate limits, security headers, CSRF protection, and production configuration checks.

5. Add metrics for activation, synchronization success, job age, and error rates.

6. Run dependency, credential, logging, authorization, and connector security reviews.

7. Execute recovery and rollback exercises in a staging environment.

Exit criteria:

- the first practical user journey passes in staging;

- operators can detect and recover common failure modes;

- deployment, backup, restore, and rollback are documented and tested;

- no critical security finding remains open.

Milestone: Personal Digital Home MVP.

Phase 5 — Marketplace and payments

Objective: support a trustworthy local product-to-payment journey.

Expected duration: 4–6 weeks.

Tasks, in order:

1. Define product, inventory, order, order-line, payment-attempt, refund, and idempotency models.

2. Build local product CRUD and public catalog/detail pages.

3. Create immutable order price snapshots and explicit order-state transitions.

4. Harden the dummy gateway contract with service and state-machine tests.

5. Implement one production gateway based on target-market priority.

6. Implement idempotent payment creation.

7. Implement signed webhook verification, replay prevention, event deduplication, and transactional state updates.

8. Build checkout, payment status, receipt, cancellation, and refund experiences.

9. Add gateway configuration with encrypted secrets and sandbox/production separation.

10. Add reconciliation and alerting for mismatched local/provider states.

Exit criteria:

- duplicate checkout submission cannot create duplicate logical payments;

- forged and replayed webhook events are rejected;

- valid duplicate webhook delivery is acknowledged without repeated transition;

- order totals cannot change after checkout creation;

- sandbox end-to-end checkout, payment, refund, and reconciliation pass.

Phase 6 — Federation

Objective: connect independent nodes without weakening local ownership or moderation.

Expected duration: 5–8 weeks after protocol selection.

Tasks, in order:

1. Select and document the federation protocol and interoperability target.

2. Implement node identity, key management, and capability discovery.

3. Add remote actor/object models with provenance and trust state.

4. Implement signed inbox/outbox delivery and verification.

5. Add delivery queue, retries, deduplication, tombstones, and update/delete semantics.

6. Add follow/block/mute/report and moderation controls.

7. Display federated content with unmistakable remote identity and canonical URLs.

8. Add public-profile connection discovery with an owner-controlled show_on_profile flag and one cached latest-post preview per connection.

9. Add cursor pagination, stale-cache indicators, non-blocking remote-failure behavior, and cycle-safe graph traversal.

10. Run interoperability, abuse, key-rotation, replay, graph-cycle, privacy-filtering, and failure tests.

Exit criteria:

- two test nodes can exchange supported activities securely;

- duplicate and replayed activities are harmless;

- remote updates/deletions follow documented semantics;

- administrators and users can block abusive nodes or actors;

- public profiles show only owner-approved, moderation-safe connections and attributed cached previews;

- cyclic graphs such as A→B→D→E→A do not cause repeated records or unbounded traversal;

- local, external, and federated ownership remain distinguishable.

Phase 7 — Ecosystem and scale

Objective: broaden integrations and operational capacity only after core semantics are stable.

Candidate work:

- OAuth social connectors;

- plugin/adapter registry and compatibility policy;

- federated commerce experiments;

- advanced search, media processing, and caching;

- multi-node operational tooling;

- accessibility, localization, import/export, and data portability improvements.

Phase 8 — AI interaction and monetization

Objective: let an owner monetize their node directly through owner-configured AI chat, paid content, and ad inventory, gated behind mandatory visitor identity.

Depends on Phase 1 (identity) and Phase 5 (payments); independent of Phase 6 (federation) and Phase 7. See <code>AI-MONETIZATION-STRATEGY.en.md</code> for the full design, data model, and rationale — this entry only sequences the work.

Tasks, in order (each numbered step below matches the strategy document's Section 12):

1. Visitor identity via Google OAuth (visitor_accounts, visitor_tokens, redirect/callback endpoints).

2. LLM provider abstraction (LLMProviderInterface, LLMProviderFactory for OpenAI/Anthropic, llm_configs).

3. Paid CV/resume access (cv_documents, cv_access_grants).

4. Paid chatbot grounded in the owner's own profile/CV content (chat_sessions, chat_messages).

5. Daily traffic and unique-visitor analytics (page_views, analytics_daily).

6. Ad banner marketplace with daily/weekly/monthly pricing (ad_slots, ad_bookings).

Exit criteria:

- a visitor can view a public profile without signing in, but is prompted for Google sign-in the moment they attempt a paid or interactive action;

- CV access and chatbot sessions are billed through the existing PaymentGatewayInterface, never a hard-coded provider;

- LLM usage is rate-limited and cost-bounded per node, and fails closed (not to a shared default) when unconfigured;

- an owner can see yesterday's unique-visitor and page-view counts;

- an advertiser's booking only goes live after the owner approves the creative, and expires automatically at the end of its paid period.

6. Tasks to start first

The next development cycle should execute these tasks in this exact order:

|---:|---|---|---|

| 1 | Define configuration and environment validation | Every route, database, secret, and job depends on predictable configuration | Config loader, validation, safe example environment file |

Do not start a production payment gateway or federation implementation before tasks 1–9 are stable. They depend on identity, authorization, persistence, error handling, auditability, and state semantics established there.

7. Dependency map

Configuration
  └─ Router + error handling
      └─ Database + migrations
          ├─ Identity + authorization
          │   ├─ Public profile
          │   ├─ Local posts + timeline
          │   │   └─ External aggregation
          │   │       └─ Federation
          │   └─ Admin operations
          └─ Products + orders
              └─ Payments + webhooks

Operations, security tests, observability, and documentation run across every branch rather than appearing only at the end.

8. Testing strategy

| Test level | Primary purpose | Examples |

|---|---|---|

| Unit | Domain rules and adapters in isolation | Money, status transitions, normalization, factory selection |

| Integration | Database and infrastructure behavior | Migrations, repositories, queue locking, idempotency |

| Contract/API | OpenAPI-aligned HTTP behavior | Auth, status codes, envelopes, validation, pagination |

| End-to-end | Critical user journeys | Register-to-profile, publish-to-timeline, connect-to-sync, checkout-to-paid |

| Security | Abuse and boundary failures | Authorization, SSRF, XSS, CSRF, webhook replay, secret leakage |

| Operational | Recovery behavior | Failed job retry, backup/restore, rollback, provider outage |

Every bug fix should add a regression test at the lowest useful level.

9. Definition of Done

A task is complete only when all applicable conditions are met:

- acceptance criteria are demonstrated;

- authorization and ownership rules are enforced;

- input validation and predictable error responses exist;

- unit/integration/HTTP tests cover success and important failure paths;

- migrations and indexes support the data path;

- logs are useful and contain no secrets or sensitive payloads;

- metrics or operational state exist for asynchronous behavior;

- English and Indonesian documentation are updated;

- OpenAPI is updated when the HTTP contract changes;

- deployment and rollback impact is understood.

10. Release gates and metrics

MVP release gates

- registration-to-public-profile and publish-to-timeline journeys pass;

- external sync succeeds repeatedly without duplication;

- authentication, authorization, SSRF, and output-sanitization reviews pass;

- migrations, backup, restore, worker, and scheduler procedures are tested;

- no critical or high-severity unresolved defect affects data ownership or exposure.

Initial product metrics

- activation rate: owner publishes a profile and one post/source;

- median time from registration to public profile;

- first-sync and recurring-sync success rates;

- percentage of timeline items with complete provenance;

- oldest queued job and retry recovery rate;

- API error rate and p95 response latency;

- payment completion and reconciliation rates after Phase 5.

11. Major risks and mitigations

| Risk | Mitigation |

|---|---|

| Scope spreads across identity, social, commerce, and federation | Enforce phase gates and protect the first content-ownership loop |

| External URLs create SSRF and parser risk | Use a hardened outbound client before user-configurable connectors |

| Provider differences leak into business logic | Keep adapters behind interfaces and normalized models |

| Async failures remain invisible | Persist job state, attempts, next retry, sanitized errors, and metrics |

| Payment duplicates or forged callbacks corrupt orders | Idempotency keys, signed webhooks, deduplication, transactional transitions |

| Federation creates abuse and trust problems | Delay until local moderation/identity semantics are stable; add block/report controls |

| Documentation diverges from implementation | Treat OpenAPI and bilingual docs as part of Definition of Done |

12. Review cadence

- Review delivery progress weekly against exit criteria, not percentage-complete estimates.

- Demonstrate one working vertical slice at the end of each iteration.

- Reassess roadmap order at every milestone, but do not bypass security or data-integrity dependencies.

- Update this roadmap when scope, protocol choice, provider priority, or team capacity changes materially.

Edit on GitHub