# Codebase Onboarding Path: Laravel/Vue microSaaS Takeover ## 1. CODEBASE ASSESSMENT - **Platform:** microSaaS — Laravel 10 + Vue 3 + MySQL + Redis, 500 users, 25K LOC - **Complexity:** High (custom billing logic + custom permission system + zero tests = high hidden-risk surface despite modest LOC) - **Documentation State:** None (sole founder-developer, no handover) - **Biggest Risk:** Hardcoded secrets (Stripe keys, mail password) sitting in config files in what may be a version-controlled repo — this is a live security/compliance exposure, not just a code-quality issue. Second risk: custom subscription billing means Stripe webhook handling and invoice state logic exist only in this developer's head, encoded in code with no tests to reveal edge cases. - **Safety Priority:** Rotate and remove hardcoded secrets, verify backup integrity, and lock down access (Forge, database, Stripe dashboard, admin accounts) before anyone touches business logic. ## 2. ONBOARDING PATH Since the engineer is senior (4 yrs Laravel, 3 yrs Vue), the timeline is compressed but **security and data-model fundamentals are not skipped** — they're inherited-codebase non-negotiables. ### Week 1: Foundation & Security Lockdown **Day 1 — Access Audit & Secrets** - Setup: Get Forge access, database credentials, Stripe dashboard access, mail provider access, domain/DNS access. Confirm who else (if anyone) has admin access to any of these. - Files to read: `config/services.php`, `.env.example` (or `.env` if committed — flag immediately if so), `config/database.php` - Concept: Where secrets currently live vs. where they should live (`.env`, not tracked in git) - Hands-on: Move every hardcoded key (Stripe, mail) out of config files into `.env`, rotate the Stripe keys in the Stripe dashboard (old ones may be exposed in git history even after removal), rotate the mail password. Confirm `.env` is in `.gitignore`. - Milestone: "By end of Day 1, no live secret exists in a committed file, and all previously-exposed keys have been rotated." **Day 2 — Backup Verification & Deployment Reality Check** - Setup: Locate and test-restore the most recent database backup to a local/staging environment. Confirm backup frequency and retention. - Files to read: Forge deployment script (or `deploy.sh` if present), any `.forge` config - Concept: What "manual deploy via Forge" actually means step-by-step — is it git push + manual button click? Are there manual steps (migrations, cache clear) a person must remember? - Hands-on: Do a full deploy to staging (or a cloned production instance) manually, documenting every step as you go — this becomes your first README. - Milestone: "You've restored a backup successfully and can deploy the app end-to-end without the previous developer." **Day 3 — Data Model Deep Dive** - Files to read: `app/Models/` (all 8, skim), the 3 custom migrations that modify core Laravel tables (read these carefully), `database/schema` dump or run `php artisan schema:dump` if not present - Concept: Why 3 migrations touch core Laravel tables — this is almost always either auth extension or permission-system wiring (Spatie). Understand exactly what was changed and why before you migrate anything else. - Hands-on: Generate an ER diagram (manually or via a tool like `laravel-erd`) of all 30 tables. Annotate which tables are "core Laravel," which are Spatie Permission, and which are custom billing. - Milestone: "You can draw the subscription → invoice → user relationship from memory." **Day 4 — Custom Billing Logic (highest-risk business logic)** - Files to read: `app/Services/` — specifically whichever service class(es) handle billing/invoicing (identify by name, likely something like `BillingService.php` or `InvoiceService.php`) - Concept: Since this isn't Laravel Cashier, there's no framework safety net — trace the full lifecycle: subscription created → recurring charge → invoice generated → failure handling. Ask: what happens on a failed payment? Is there retry logic? Dunning? - Hands-on: Trace one full billing cycle in code, from the Stripe webhook endpoint (check `routes/api.php` for the webhook route) through to invoice record creation. Write down every assumption the code makes about Stripe's behavior. - Milestone: "You can explain what happens, step by step, when a customer's card is declined." **Day 5 — Permissions & Roles** - Files to read: Spatie Permission config, seeder or migration that defines roles, one controller that uses permission middleware/gates - Concept: What roles exist, what they can do, and whether the custom migrations from Day 3 altered Spatie's default behavior - Hands-on: Map every role to what it can access. Test logging in as each role type in staging. - Milestone: "By end of Week 1, you can independently secure, deploy, back up, and explain billing + permissions for this app — without the founder." ### Week 2: CI/CD & First Tests **Day 6-7 — CI/CD Pipeline Setup** - Set up GitHub Actions (or your CI tool of choice) for: lint → test → deploy-on-merge-to-main. Start simple; Forge deploy can stay manual initially or be triggered via webhook. - Hands-on: First green CI run on a trivial PR. - Milestone: "A pull request now runs automated checks before merge." **Day 8-9 — First Tests on Critical Paths** - Priority order for test coverage: (1) billing/invoice generation logic, (2) permission/role access checks, (3) the 4 queue jobs (especially the report jobs, since scheduled job failures are silent by default). - Hands-on: Write feature tests for the Stripe webhook handler and one permission gate. This is the highest-leverage testing you can do given zero existing coverage. - Milestone: "The riskiest untested code path (billing) now has at least basic regression coverage." **Day 10 — Review & Stabilization Check-in** - Self-review: has anything broken in staging? Any surprises from testing that reveal bugs in the inherited billing logic? - Milestone: "You feel confident this app won't silently break from a change you make." ### Week 3: First Feature — Export to Excel **Day 11-12 — Design & Data Access** - Files to read: the controller for whichever report(s) need exporting, relevant Eloquent model/query - Hands-on: Add `maatwebsite/excel` (Laravel Excel) package, scaffold an Export class for the target report. - Milestone: "Export class generates a correct .xlsx for a single report type in local dev." **Day 13-14 — Ship It** - Hands-on: Add the frontend trigger (Vue component/button), wire to a new export route, test via CI, deploy through the now-functioning pipeline. - Milestone: "First feature shipped through your own CI/CD pipeline, with a test covering the export endpoint." ## 3. CONCEPT MASTERY CHECKLIST | # | Concept | Verification Method | Priority | |---|---------|---------------------|----------| | 1 | Secrets management (.env vs config) | No secrets remain in committed files; keys rotated | Must | | 2 | Custom billing lifecycle | Can verbally trace subscription→charge→invoice→failure | Must | | 3 | Core-table migrations impact | Can explain what each of the 3 migrations changed | Must | | 4 | Spatie role/permission mapping | Can list every role and its access scope | Must | | 5 | Backup/restore process | Has successfully restored a backup | Must | | 6 | Deployment process (Forge) | Has deployed independently without prior notes | Must | | 7 | Redis usage split (cache vs queue) | Can identify which keys/queues serve which purpose | Should | | 8 | Scheduled report jobs | Knows schedule, can manually trigger and verify output | Should | | 9 | CI/CD pipeline | Pipeline runs green on a real PR | Should | | 10 | Frontend state (Pinia) architecture | Can trace one store's data flow to a component | Nice | ## 4. CRITICAL FILE MAP | Category | File Path | Why It Matters | When to Read | |----------|-----------|-----------------|---------------| | Secrets | `config/services.php` | Currently holds hardcoded keys | Day 1 | | Env | `.env` / `.env.example` | Where secrets should live | Day 1 | | Deployment | Forge deploy script | Only record of the deploy process | Day 2 | | Migrations | The 3 core-table migrations | Non-standard Laravel behavior lives here | Day 3 | | Data Model | `app/Models/*.php` (8 files) | Full domain model | Day 3 | | Billing | `app/Services/BillingService.php` (or equivalent) | Custom, untested, highest financial risk | Day 4 | | Billing | Stripe webhook route in `routes/api.php` | Entry point for all payment events | Day 4 | | Permissions | Spatie seeder/config | Defines the entire access model | Day 5 | | Jobs | `app/Jobs/*.php` (4 files) | Scheduled/queued logic, silent-failure risk | Day 5 | | Frontend entry | `resources/js/app.js` (or main entry) | Vue app bootstrap, Pinia store registration | Week 2 | | Reports | Controller behind target export report | Target for Week 3 feature | Day 11 | ## 5. KNOWN LANDMINES | Landmine | Location | Why It's Dangerous | How to Navigate | |----------|----------|---------------------|-------------------| | Hardcoded secrets | `config/services.php` and possibly `.env` in git history | Live credentials exposed to anyone with repo access, including in git log even after removal | Rotate keys immediately, purge from git history if repo is ever made public/shared | | Custom billing (no Cashier) | `app/Services/` billing class | No framework safety net; edge cases (failed payments, proration, cancellation) are hand-rolled and untested | Trace every code path before modifying; write tests before touching | | Core-table migrations | 3 custom migrations | Could conflict with future Laravel upgrades or Spatie package updates if they altered expected schema | Document exactly what changed; treat any framework/package upgrade as high-risk until reviewed | | No tests, no CI | Entire codebase | Any change could silently break billing or permissions with no automated signal | Prioritize test coverage on billing/permissions before adding new features | | Manual Forge deploy | Deployment process | Undocumented manual steps could be forgotten, causing partial/broken deploys | Document every step Day 2; automate what you can in Week 2 | | Scheduled report jobs | `app/Jobs/` | Failures in scheduled jobs are often silent unless explicitly logged/alerted | Add failure logging/alerting as part of Week 2 stabilization | ## 6. MENTOR CHECKPOINTS Since the founder is gone, there's no internal mentor — these become **self-checkpoints** or, ideally, points to loop in a trusted senior engineer/consultant for a second pair of eyes: | Day | Checkpoint | What to Review | |-----|-----------|-----------------| | 1 | Secrets rotated | Confirm no keys remain exposed anywhere, including git history | | 3 | Data model + migrations understood | Can you explain the 3 core-table changes to someone else? | | 5 | Billing logic traced | Walk an outside reviewer through the billing lifecycle — fresh eyes often catch what you've normalized | | 10 | CI/CD + first tests | Confirm pipeline actually blocks bad merges, not just runs | | 14 | First feature shipped | Full review of the export feature before wider rollout | --- A note on sequencing: given the hardcoded secrets, I'd treat Day 1 as non-negotiable even if it feels like it's cutting into "real" onboarding time — an exposed Stripe key on a live 500-user billing system is the kind of risk that outranks everything else on this list.