Skip to content

00 — Context

Problem statement

Adventive's internal administrative interface is a single legacy application (adventive-admin, BitBucket-hosted, version 3.3.9) that handles two distinct responsibility domains:

  1. Customer service-level management — operator tooling for managing customer accounts, tiers, entitlements, and configuration.
  2. Billing — invoice generation, line-item rollup, Stripe invoice creation via API, custom invoice PDF rendering, and email delivery via Mailgun.

The application mixes API logic with presentation in a single codebase, does not reflect current Adventive brand guidelines, and has accumulated pain points typical of a long-lived internal tool. It is also the coupling point for a custom billing flow that the Stripe Billing Transition project will evaluate for replacement.

Repo analysis (April 2026) surfaced two findings that raise the urgency of migration beyond architectural debt alone:

  • Production AWS and Bitbucket credentials are hardcoded in source (application/config/adventive.php) — a live secret-exposure risk in every clone and CI artifact.
  • CSRF protection is globally disabled and Duo 2FA is currently bypassed — the admin's only active access control is JumpCloud username/password.

Business motivation

  • Architectural debt: the admin is the last major internal surface not yet aligned with Adventive's API-first / Cloudflare Workers direction (Public API migration landed 2026-04; Cloudflare Tunnel landed prior).
  • Secret exposure: AWS access keys, S3 secrets, and Bitbucket OAuth credentials are committed to source for all three environments. Remediation is blocked until secrets are moved to a managed store; this migration provides the natural forcing function.
  • Security posture: CSRF disabled (config.php:320), Duo 2FA bypassed (latest auth commit), payment links secured only by MD5 hash (Billing.php:561). Cloudflare Access restores edge-enforced MFA and eliminates application-managed auth entirely.
  • Presentation coupling: mixing presentation and API logic makes it hard to evolve either independently; a future mobile or partner-facing admin surface is effectively blocked.
  • Brand drift: the visual layer predates the current brand system and reads as legacy to internal users.
  • Billing entanglement: the admin owns both the billing UI and meaningful billing business logic. That logic is the scope-of-analysis input for the sibling Stripe Billing Transition project — separating presentation from API is a prerequisite for cleanly migrating billing.
  • Dependency risk: phpoffice/phpexcel 1.7.9 (archived 2019, no security patches) is installed alongside its successor phpspreadsheet. CodeIgniter 3.1.* receives no active maintenance.

Scope

  • In scope:
  • Architecture audit of adventive-admin (routes, data model, integrations, auth). ✓ Complete — see §01.
  • Serverless viability assessment for the API layer (Cloudflare Workers fit). ✓ Complete — see §01.
  • Target architecture: separate API Worker + Cloudflare Pages SPA. ✓ Decided.
  • UI refresh aligned with current Adventive brand guidelines.
  • Auth/authz model: Cloudflare Access for operator identity, application RBAC for authorization. ✓ Decided.
  • Migration plan with phased cutover and rollback. ✓ See §02.

  • Documentation: full planning deliverable set → PDF → Claude Code handoff package.

  • Out of scope:

  • Billing business logic redesign — owned by ../Stripe Billing Transition/. This project defines the seam; that project decides what lives on which side of it.
  • Public-facing customer UI.
  • Migration of the underlying customer / account / billing data stores (unless assessment surfaces a forced dependency — it did not).

  • Partner-specific scheduled reports (Reporting.php, 25 methods) — deferred; evaluated for a dedicated analytics service in Phase 4.

  • Deferred:

  • Mobile or offline operator access.
  • External partner/reseller admin surfaces.
  • Feature additions beyond parity with the current admin.
  • Directory provider choice for Cloudflare Access (JumpCloud vs. Google Workspace) — deferred per ADR.

Success criteria

  1. Written and signed architecture plan matching the Adventive Engineering PDF standard. ✓ This document.
  2. Clear API contract definition (OpenAPI via @hono/zod-openapi) that billing, service-level management, and any future consumer can build against.
  3. Presentation layer demonstrably decoupled — can be rebuilt or replaced without touching the API.
  4. Brand-guideline review sign-off on the new UI direction (reference: brandguide.adventive.com/dashboard).
  5. Cutover plan with rollback path and defined success metrics (operator task completion time, error rate parity or better).
  6. Implementation handoff package ready for Claude Code (CLAUDE.md, PLAN.md, kickoff doc — matching Public API pattern).
  7. Production secrets removed from source and moved to AWS Secrets Manager or Cloudflare secrets before implementation begins.

Stakeholders

Role Name Interest
Owner Jeffrey Lambert Architecture, plan quality, delivery
Approver — UI Jeffrey Lambert Brand alignment, UX sign-off
Approver — API Patrick API contract, backend architecture sign-off
Approver — Billing UI Jeffrey + Patrick Joint sign-off on billing surface area of the admin
Informed Adventive operations team (~10 operators) End users of the new admin

Operator population and RBAC tiers

~10 operators total, across three permission tiers:

Tier Count Capabilities
Super-admin 2 All functionality across customer, service-level, billing, and tooling domains
Billing TBD Billing-scoped operations (invoices, payments, managed services, reports). Read access to accounts.
Read-only TBD Read access across all surfaces, no mutations

The two super-admins are the only tier with authority to destructive / cross-domain operations. Billing-tier operators can read all customer context but only write billing-domain records.

Design reference

Visual and interaction language target: https://brandguide.adventive.com/dashboard — the Adventive brand-guide dashboard concept. "Similar in design, refined for utility." Not a literal reskin; the admin's job is operator efficiency first.

Project sequencing

This project runs first, ahead of the Stripe Billing Transition migration phase. Rationale:

  • The presentation/API separation is a prerequisite for cleanly migrating billing — you can't cleanly replace a subsystem that shares a codebase with its UI.
  • The new admin will surface whatever billing decision gets made downstream (custom, Stripe-native, or hybrid), so it needs to be designed to tolerate that outcome without rework.
  • Admin-first also front-loads the architectural work that the billing project will consume.
  • The secret-exposure and auth-gap findings make this more urgent, not less.

The billing project can kick off in parallel at its viability-assessment phase, but its migration-plan phase should land after the admin API contract stabilizes.