Product app goal sheet

Status: initial draft, open for refinement. Updated: 29 October 2026.

See the PostgreSQL schema for tables, ownership constraints, and remaining persistence decisions.

The schema dependency HLD shows which tables stand alone and which reference other tables.

The Spring Boot container + Supabase PostgreSQL reference design explains the access boundary and request/response HLD.

The product backend guide records what the service implements today: Google sign-in, backend token pairs, and persisted sessions. Profile, API-key, usage, payment, and redeem-code behavior remain planned.

Build a customer-facing astrology API product where users can sign in, try the API, manage access keys, see their usage, and pay for access. Keep the existing documentation app as the internal engineering documentation site, extracting customer-facing pages into a separate product app.

This sheet records requested goals and proposed delivery criteria. Unchecked items are planned work, not implemented capabilities. Suggested responsibilities and policies remain open until agreed.

Requested scope

“Lightweight profile” is the working interpretation of “use profile soft not much.” Exact fields remain open.

Pages and user journey

Proposed primary journey: home or developer docs → Google login → dashboard → create a key → make a request → inspect usage → purchase access when needed.

Existing app and extraction

The current repository has a documentation frontend with optional product pages and a playground. Its HTTP API currently uses an application-level API key; customer accounts, customer-owned keys, usage plans, and billing are additional goals. Production browser requests already need a server-side boundary that owns backend credentials.

• [ ] Inventory existing routes, product copy, developer material, and playground components before moving them.
• [ ] Extract customer-facing pages into the product app and reuse suitable shared components.
• [ ] Keep engineering designs, research, package internals, and operational guides in internal docs.
• [ ] Define public developer docs separately from engineering docs, including ownership of shared API examples.
• [ ] Decide internal-docs hosting, access restrictions, and redirects before switching navigation or domains.
• [ ] Keep both apps buildable during extraction and preserve the existing API while the new boundary is introduced.

Calling the app “internal” does not itself restrict access. Access enforcement is a separate migration requirement to resolve.

Backend responsibilities — proposed

The requested runtimes are fixed goals; this allocation is a starting point for discussion.

The Native/Ktor service needs a feasibility check before this split is accepted. No calculation rewrite is assumed in the first release. Define how revocations, rate policies, and account entitlements reach the request-serving service before implementation.

Implemented today in the Spring Boot service: Google sign-in, backend access/refresh token issuance, and database-backed session validation. The service does not yet expose profile, key, usage, payment, or redeem-code routes.

Capability checklist and acceptance criteria

Identity and profile

• [ ] Google sign-in creates or retrieves an account using a stable provider identity.
• [ ] A user can sign out; failed or cancelled login offers a clear retry path.
• [ ] Track user-owned sessions, support finite and non-expiring sessions, and allow individual or all-session revocation as described in the schema.
• [ ] Keep app_user to ID and timestamps; store provider subject and contact in login_identity, and optional display name in a user-owned profile as described in the schema.
• [ ] Account data, keys, usage, and payment history are visible only to their owner.

API keys

• [ ] A signed-in user can create a named key; show its full value once and retain a non-reversible verifier.
• [ ] List key labels, identifying prefixes, creation dates, and current status without exposing full secrets.
• [ ] A user can revoke their own key; define and verify the maximum revocation propagation delay.
• [ ] Invalid and revoked keys cannot reach the calculation backend.
• [ ] Customer keys and internal backend credentials remain separate; internal credentials stay out of browser assets and logs.

Key count limits, expiry, rotation, and scopes remain open. They are not assumed for the initial release.

Routing, counting, and request limits

• [ ] Resolve an accepted key to its owning user before forwarding a request.
• [ ] Forward only supported routes and methods; preserve relevant responses and correlation information.
• [ ] Attribute requests across all of a user’s keys to that user, with optional per-key breakdown.
• [ ] Show usage for a clearly identified reporting period in the dashboard.
• [ ] Define whether rejected, failed, retried, and timed-out requests count toward displayed usage and paid allowance.
• [ ] Make usage reporting resilient to duplicate delivery and document any reporting delay.
• [ ] Enforce configurable request rates across service instances; define burst and sustained limits.
• [ ] Distinguish a short-term rate limit from an exhausted plan allowance, with documented recovery behavior.
• [ ] Define behavior when key validation, rate state, or usage storage is unavailable.

The product playground should use the same entitlement and counting policies as customer API calls unless an explicit exception is agreed.

Razorpay payments through orders

Requested approach: the backend creates a Razorpay order for a selected offering; the frontend opens checkout using that order; the backend verifies the payment result before granting access. Exact integration contracts will be verified against provider documentation during implementation.

• [ ] Determine price, currency, and purchased entitlement on the server.
• [ ] Associate the provider order with the signed-in user and a local purchase record.
• [ ] Verify payment authenticity and the required successful payment state before granting entitlement.
• [ ] Handle browser callbacks and provider notifications without granting the same entitlement twice.
• [ ] Show pending, successful, failed, and cancelled outcomes; reconcile payments when the browser never returns.
• [ ] Define how refunds, disputes, and expired or unused purchases affect access.

Order-based purchases are the initial direction. Recurring subscriptions, credit packs, allowance periods, and upgrade rules remain decisions rather than implied features.

Redeem codes — later phase

• [ ] Define codes that grant a subscription without payment, with active state and optional redemption expiry.
• [ ] Track the consuming user and granted subscription as described in SCHEMA.md.
• [ ] Create the grant and consumption record atomically; retries must not grant duplicate access.
• [ ] Agree code limits, eligibility, and subscription stacking before enabling redemption.

Delivery milestones

Decisions to refine next

Refinement record

Update this sheet as decisions are made. Mark a goal complete only when its acceptance criteria have evidence; record scope changes here so later implementation follows the agreed plan.

Current references

• Product backend guide: current service capabilities, configuration, routes, and documentation map.
• Authentication: Google verification, token claims, sessions, and failure paths.
• HTTP API: implemented routes, examples, and error contract.
• Database schema: tables, relationships, ownership rules, and manual application.
• Production architecture: proposed Cloudflare container and Supabase PostgreSQL path.
• Local development: Compose, host JVM, configuration, IDE, and commands.
• Native builds: GraalVM native compilation and reflection registration.
• Repository overview: current docs app, product flags, playground behavior, and production credential boundary.
• HTTP API guide: existing calculation API behavior and entry points.
• Current frontend pages: source pages to inspect during extraction.
• Current API app: existing backend host to retain or migrate deliberately.