Roadmap
Update this document in the pull request that changes a milestone’s state. Completed items should link to their evidence: a pull request, release, or deployment record.
Prioritization policy
This roadmap is the source of truth for delivery sequencing. Prioritize work in this order:
- Security, correctness, and broken delivery paths.
- Capabilities required to run and observe the existing platform reliably.
- The next dependency-free domain milestone that advances the commerce flow.
- Developer experience and documentation that reduce repeated operational work.
- Architecture improvements, including BFF composition, only when they are tied to a demonstrated client or operational need.
Every material pull request must update the relevant documentation in this repository: architecture for boundary changes, operations for runtime or deployment changes, development guidance for workflow changes, and this roadmap when milestone status or priority changes.
| Milestone | Status | Outcome |
|---|---|---|
| Identity authorization hardening | In progress | Product Service enforces the Keycloak admin role for catalog mutations. Order Service enforces token-subject ownership for orders and carts, scopes customer lists, and reserves cross-customer order access for realm admin. Argo CD/Grafana role and callback examples are validated (Argo validation, Helm CI); live issuer/secrets/client configuration and legacy HS256 retirement remain. Kiali activation is gated on Kubernetes API OIDC/RBAC, and Kibana OIDC is gated on an Elastic SSO license. |
| Platform foundation | Complete | User service, Helm chart, Argo CD, Kind, scripts, and documentation repositories created |
| Identity and authorization | In progress | Keycloak/OIDC is the target authority; the local realm, BFF JWKS validation, web PKCE foundation, Android/iOS native PKCE flows, platform-tool role contract/examples, and downstream JWKS rotation handling are implemented. BFF admin routes require a verified admin role; Product Service supports strict OIDC precedence, and BFF/Product/Order/Inventory verify discovery issuer and refresh unknown signing key IDs. The legacy User Service HS256 JWT path and separate Order-to-Product service JWT remain transitional; callback validation, confidential secrets, tool-specific RBAC, and password-login retirement remain next |
| Eventing and analytics platform | In progress | Order Service writes transactional OrderCreated, CartUpdated, and CartCleared records to a PostgreSQL outbox, while Inventory writes transactional stock/reservation events to its own outbox; both optional publishers use expiring PostgreSQL leases and separate Kafka topics. Kafka remains an opt-in integration: no Kafka/CFK is installed by local Argo bootstrap, and an external broker is required before enabling delivery; consumer idempotency and downstream analytics projections remain next |
| API contracts and transports | Complete | gRPC contracts, explicit HTTP handlers, OpenAPI generation, and transport authorization |
| Production readiness | In progress | User, Product, Inventory, and Order Services expose the shared /metrics contract with Go/process collectors; all four charts provide opt-in Prometheus scraping, while live discovery and production storage/access validation remain environment work |
| Delivery automation | Complete | CI, linting, security scans, CodeQL, container validation, semantic release configuration, and Helm validation |
| Feature management | In progress | The Go BFF has an OpenFeature boundary with the official Flagsmith provider, safe defaults, and a client-safe /api/v1/config response (BFF commit 414b258); the opt-in self-hosted Flagsmith Argo application is published (Argo commit bba8f5b); and Next.js now consumes the BFF flags with local defaults (frontend commit 4bdca9f). Helm configuration is opt-in (Helm commit 2dc5456); native clients now load the client-safe flags with local fallbacks (Android commit 483fabd, iOS commit a51b4f9). Governance and the architecture guidance are documented in feature management; environment key activation remains next. GitHub Actions and Helm continue to own infrastructure/deployment flags; Keycloak remains the identity and authorization authority. |
| Local platform bootstrap | Complete | Repeatable Kind and Argo CD scripts merged in storemesh-scripts pull request #1; the disposable GitHub Actions Kind platform smoke is green, including application readiness, Istio gRPC enrollment, demo catalog/inventory/order traffic, and observability validation (run 33857216027) |
| Local data services | Complete | Development-only PostgreSQL and Redis bootstrap is implemented and validated in storemesh-scripts pull request #4 |
| GitOps deployment verification | Complete | Argo CD synchronized the user service; PostgreSQL, Redis, and two user-service replicas reached healthy state in the recreated Kind cluster |
| Additional domain services | Complete | Product, Inventory, and Order Services are deployed and healthy in the local Kind cluster. Inventory uses PostgreSQL-backed replica-safe reservations (runtime PR #2); Order consumes Product and Inventory gRPC contracts, authenticates to Product with service JWTs, coordinates price snapshots and reservations, and supports PostgreSQL-backed idempotent retries. The deployed workflow was verified end to end, including a successful order, a same-key retry, and persistent stock reduction. |
| Edge composition / BFF | In progress | Go BFF exposes REST/JSON for resource and operational routes plus authenticated GraphQL queries and mutations for products, cart, orders, cart replacement, and idempotent order creation, backed by canonical internal gRPC APIs. Canonical v1 fixtures are aligned across BFF, Android, iOS, and Next.js; route authentication, protected resolver, and idempotency-key schema tests now provide regression coverage. Production promotion remains pending environment setup; network-backed client integration remains next. |
| Web frontend | In progress | Next.js, React, and TypeScript frontend provides Keycloak login, GraphQL-backed catalog/cart/order/checkout flows, a role-aware admin area, and REST-backed cancellation/admin operations. Deterministic Playwright fixtures remain the default, while an opt-in live browser flow now validates the real BFF catalog/cart/order path with a supplied token. Native local Product Service mode provides 32 demo products with deterministic SKU-based visuals for storefront testing. Payment, fulfillment, GraphQL cancellation, and admin mutations remain future scope. |
| Native mobile clients | In progress | Android and iOS have native splash/login, Keycloak PKCE, secure Keychain/Keystore sessions, configurable localhost/ngrok routing, catalog search/filtering, product details, order history, and native cart/checkout foundations. Both clients now include opt-in network-backed commerce tests for product/cart/order/clear flows against an independently running BFF; Android runs them through the hosted emulator suite when configured, while normal CI skips them without credentials. Further hosted mobile integration and authorization validation remain next. |
| Documentation platform evolution | In progress | Next.js + TypeScript site consumes canonical Markdown and provides responsive navigation, client-side search, an interactive architecture map, versioned routes, and a BFF API explorer. GitHub Pages publishing is active and was revalidated with the latest content (deployment); richer API execution remains future scope. |
| Production platform hardening | In progress | Domain Helm charts include one-replica PodDisruptionBudgets and gRPC ingress NetworkPolicies (PR #9), opt-in ExternalSecret resources (PR #10), an opt-in User Service HTTPS Ingress (PR #11), a pinned cert-manager Argo CD application (PR #4), a non-applied Let's Encrypt issuer template (PR #5), opt-in Prometheus alert rules (PR #12), and Istio sidecar enrollment with applied STRICT mTLS plus service-account-principal AuthorizationPolicy rules (Argo CD commit c9999e5, scripts commit 16fa12d). The complete mesh path is runtime-validated on disposable Kind, including sidecars, strict mTLS, principal authorization, gRPC traffic, and observability (workflow run 34285795009). A non-applied production edge template now covers HTTPS Gateway routing, Keycloak JWT validation, and conservative BFF resilience settings; activation requires environment-specific hostname, TLS, and issuer values. Istio remains optional to install per environment. Remaining mesh work is environment activation and mobile network integration coverage. Staged observability now covers Prometheus/Grafana/Alertmanager (monitoring PR #8), OpenTelemetry with Istio telemetry when the mesh is enabled (Tempo PR #9, Istio PR #11), and ECK-managed Elasticsearch/Kibana with Fluent Bit (operator PR #6, logging template PR #7, Fluent Bit template PR #10). Backup/recovery requirements and an environment activation checklist are documented; restore evidence and approved production activation remain next |
Milestone definition of done
A milestone is complete when its API and operational behavior are documented, tests and checks pass, deployment configuration exists where relevant, and the roadmap is updated with evidence.
Next prioritized work
- Activate Argo CD and Grafana OIDC in an environment with a browser-and-pod- reachable issuer, exact callback URLs, and out-of-band client Secrets. The latest chart/example changes and callback/role contracts are CI-validated; no live issuer or client secrets are configured in the development repos. Configure Kubernetes API OIDC/RBAC before enabling Kiali SSO; use Kibana OIDC only where the Elastic license includes SSO. Then remove direct User Service password login after migration evidence.
- Maintain the BFF GraphQL contract in Android and iOS, and add client integration tests for cart persistence and order creation. Canonical v1 fixtures are now aligned across BFF, Android, iOS, and Next.js; BFF route authentication, protected resolver, and idempotency-key validation have regression tests. The Android Compose smoke checks are now part of the hosted emulator job; keep local application development independent of Docker and Kind.
- Add cross-repository API/UI integration tests and harden admin/order authorization, including GraphQL resolver authorization tests.
- Enable
ServiceMonitorresources and verify Prometheus discovery and scrape health across all domain services. - Publish Cart and Inventory events, add consumer idempotency, and build the first Kafka analytics projection.
- Complete restore rehearsal, HTTPS/cert-manager activation, and Fluent Bit redaction/TLS validation in a controlled environment.
- Add GraphQL cancellation/admin mutations only after authorization, idempotency, and audit requirements are defined; keep mobile releases SemVer-tagged through Actions. platform repositories' manually triggered GitHub Actions workflows.