# Operations & Implementation

# LinkUp Source Map

## Purpose

This page records the source material used to build the first local BookStack knowledge base. Use it when checking whether an article matches the actual LinkUp implementation.

## Primary source docs

<table id="bkmrk-source-use-notes-lin"><tbody><tr><th>Source</th><th>Use</th><th>Notes</th></tr><tr><td>`LINKUP_PLATFORM_PLAN.md`</td><td>Platform-wide feature inventory, payments, tickets, security, infrastructure.</td><td>Some sections are plan-level and must be verified before publishing as live behavior.</td></tr><tr><td>`backend/FRONTEND_PROGRESS.md`</td><td>Frontend and BookStack status.</td><td>Confirms local BookStack and help-center wiring.</td></tr><tr><td>`backend/FRONTEND_AUDIT.md`</td><td>Public frontend and organizer-panel gaps.</td><td>Useful for marking partial or missing features.</td></tr><tr><td>`backend/FILAMENT_MIGRATION_COMPLETE.md`</td><td>Admin panel migration inventory.</td><td>Use to confirm which admin resources exist.</td></tr><tr><td>`backend/ADMIN_AUDIT.md`</td><td>Admin options to keep, add, hide, and audit risks.</td><td>Useful for internal/admin KB pages.</td></tr><tr><td>`backend/INVESTIGATION_TODO.md`</td><td>Known technical gaps.</td><td>Use to avoid overclaiming account, event, currency, and security behavior.</td></tr><tr><td>`backend/TEST_PLAN.md`</td><td>Manual verification scenarios.</td><td>Use for checklist wording.</td></tr><tr><td>`backend/CUTOVER_RUNBOOK.md`</td><td>Production deployment steps.</td><td>Internal operations only.</td></tr><tr><td>`deployment-docs/README.md`</td><td>Post-modernization deployment checklist.</td><td>Internal operations only.</td></tr></tbody></table>

## Current implementation anchors

<table id="bkmrk-area-status-evidence"><tbody><tr><th>Area</th><th>Status</th><th>Evidence to check</th></tr><tr><td>BookStack local help center</td><td>Implemented</td><td>`backend/docker/bookstack/compose.yml` and `https://help.linkupcompanion.app`.</td></tr><tr><td>LinkUp help redirect</td><td>Implemented</td><td>`/help` redirects to `config('services.help.url')`.</td></tr><tr><td>Filament admin</td><td>Implemented / Needs Verification</td><td>Admin resources and pages under `backend/app/Filament`.</td></tr><tr><td>Organizer panel</td><td>Partial</td><td>Organizer resources exist; audit notes list missing workspace/team/scanner/promo flows.</td></tr><tr><td>Offline reservations</td><td>Partial / Needs Verification</td><td>Two-step checkout and hold models exist; full user flow needs testing.</td></tr><tr><td>Scanner operations</td><td>Needs Verification</td><td>Scanner app and scan models exist; offline and duplicate scan behavior need hands-on tests.</td></tr></tbody></table>

## Rule for future articles

When an article depends on code, docs, or a screenshot that has not been checked in the running app, mark it as **Needs Verification**.

## Gaps / notes

- This source map is not a replacement for testing.
- Add links to exact BookStack pages after the first review pass.
- Add screenshots only after the current UI labels are confirmed.

# Local BookStack setup

## Public help

Document how local BookStack runs and how to avoid deleting existing help-center data.

## Operating guidance

This is an internal implementation document. It should help LinkUp decide what is true, what is missing, and what needs testing next.

## Source rule

Use repo docs, running screens, and test results as source material. If sources disagree, mark the feature as **Needs Verification**.

## Implementation status

<table id="bkmrk-expected-behaviorsta"><tbody><tr><th>Expected behavior</th><th>Status</th><th>Surface</th><th>Manual check</th></tr><tr><td>Operational guidance reflects current repo state.</td><td>Needs Verification</td><td>Docs / Code / Running app</td><td>Compare the page against current repo docs and screens.</td></tr><tr><td>Public KB claims are backed by implementation checks.</td><td>Implemented</td><td>BookStack process</td><td>Each article includes an implementation status table.</td></tr></tbody></table>

## Verification checklist

- Check source docs.
- Check running local app if needed.
- Update status labels after verification.
- Link related public help pages.

## Gaps / notes

- This is a living internal book and should be revised as implementation changes.
- Some pages intentionally summarize runbooks instead of replacing them.

# BookStack publishing workflow

## Public help

Document the working process for drafting, reviewing, verifying, and publishing KB articles.

## Operating guidance

This is an internal implementation document. It should help LinkUp decide what is true, what is missing, and what needs testing next.

## Source rule

Use repo docs, running screens, and test results as source material. If sources disagree, mark the feature as **Needs Verification**.

## Implementation status

<table id="bkmrk-expected-behaviorsta"><tbody><tr><th>Expected behavior</th><th>Status</th><th>Surface</th><th>Manual check</th></tr><tr><td>Operational guidance reflects current repo state.</td><td>Needs Verification</td><td>Docs / Code / Running app</td><td>Compare the page against current repo docs and screens.</td></tr><tr><td>Public KB claims are backed by implementation checks.</td><td>Implemented</td><td>BookStack process</td><td>Each article includes an implementation status table.</td></tr></tbody></table>

## Verification checklist

- Check source docs.
- Check running local app if needed.
- Update status labels after verification.
- Link related public help pages.

## Gaps / notes

- This is a living internal book and should be revised as implementation changes.
- Some pages intentionally summarize runbooks instead of replacing them.

# LinkUp status map

## Public help

Track whether major LinkUp features are implemented, partial, legacy only, missing, planned, or need verification.

## Operating guidance

This is an internal implementation document. It should help LinkUp decide what is true, what is missing, and what needs testing next.

## Source rule

Use repo docs, running screens, and test results as source material. If sources disagree, mark the feature as **Needs Verification**.

## Implementation status

<table id="bkmrk-expected-behaviorsta"><tbody><tr><th>Expected behavior</th><th>Status</th><th>Surface</th><th>Manual check</th></tr><tr><td>Operational guidance reflects current repo state.</td><td>Needs Verification</td><td>Docs / Code / Running app</td><td>Compare the page against current repo docs and screens.</td></tr><tr><td>Public KB claims are backed by implementation checks.</td><td>Implemented</td><td>BookStack process</td><td>Each article includes an implementation status table.</td></tr></tbody></table>

## Verification checklist

- Check source docs.
- Check running local app if needed.
- Update status labels after verification.
- Link related public help pages.

## Gaps / notes

- This is a living internal book and should be revised as implementation changes.
- Some pages intentionally summarize runbooks instead of replacing them.

# Production cutover checklist

## Public help

Summarize the production cutover runbook in a simple operational format.

## Operating guidance

This is an internal implementation document. It should help LinkUp decide what is true, what is missing, and what needs testing next.

## Source rule

Use repo docs, running screens, and test results as source material. If sources disagree, mark the feature as **Needs Verification**.

## Implementation status

<table id="bkmrk-expected-behaviorsta"><tbody><tr><th>Expected behavior</th><th>Status</th><th>Surface</th><th>Manual check</th></tr><tr><td>Operational guidance reflects current repo state.</td><td>Needs Verification</td><td>Docs / Code / Running app</td><td>Compare the page against current repo docs and screens.</td></tr><tr><td>Public KB claims are backed by implementation checks.</td><td>Implemented</td><td>BookStack process</td><td>Each article includes an implementation status table.</td></tr></tbody></table>

## Verification checklist

- Check source docs.
- Check running local app if needed.
- Update status labels after verification.
- Link related public help pages.

## Gaps / notes

- This is a living internal book and should be revised as implementation changes.
- Some pages intentionally summarize runbooks instead of replacing them.

# Deployment preflight checklist

## Public help

List checks that should pass before deploying the modernized platform.

## Operating guidance

This is an internal implementation document. It should help LinkUp decide what is true, what is missing, and what needs testing next.

## Source rule

Use repo docs, running screens, and test results as source material. If sources disagree, mark the feature as **Needs Verification**.

## Implementation status

<table id="bkmrk-expected-behaviorsta"><tbody><tr><th>Expected behavior</th><th>Status</th><th>Surface</th><th>Manual check</th></tr><tr><td>Operational guidance reflects current repo state.</td><td>Needs Verification</td><td>Docs / Code / Running app</td><td>Compare the page against current repo docs and screens.</td></tr><tr><td>Public KB claims are backed by implementation checks.</td><td>Implemented</td><td>BookStack process</td><td>Each article includes an implementation status table.</td></tr></tbody></table>

## Verification checklist

- Check source docs.
- Check running local app if needed.
- Update status labels after verification.
- Link related public help pages.

## Gaps / notes

- This is a living internal book and should be revised as implementation changes.
- Some pages intentionally summarize runbooks instead of replacing them.

# Rollback and backup checklist

## Public help

Document backup, rollback, and restore expectations.

## Operating guidance

This is an internal implementation document. It should help LinkUp decide what is true, what is missing, and what needs testing next.

## Source rule

Use repo docs, running screens, and test results as source material. If sources disagree, mark the feature as **Needs Verification**.

## Implementation status

<table id="bkmrk-expected-behaviorsta"><tbody><tr><th>Expected behavior</th><th>Status</th><th>Surface</th><th>Manual check</th></tr><tr><td>Operational guidance reflects current repo state.</td><td>Needs Verification</td><td>Docs / Code / Running app</td><td>Compare the page against current repo docs and screens.</td></tr><tr><td>Public KB claims are backed by implementation checks.</td><td>Implemented</td><td>BookStack process</td><td>Each article includes an implementation status table.</td></tr></tbody></table>

## Verification checklist

- Check source docs.
- Check running local app if needed.
- Update status labels after verification.
- Link related public help pages.

## Gaps / notes

- This is a living internal book and should be revised as implementation changes.
- Some pages intentionally summarize runbooks instead of replacing them.

# Security and access-control checklist

## Public help

Track admin access, roles, permissions, secrets, 2FA gaps, and Cloudflare Access plans.

## Operating guidance

This is an internal implementation document. It should help LinkUp decide what is true, what is missing, and what needs testing next.

## Source rule

Use repo docs, running screens, and test results as source material. If sources disagree, mark the feature as **Needs Verification**.

## Implementation status

<table id="bkmrk-expected-behaviorsta"><tbody><tr><th>Expected behavior</th><th>Status</th><th>Surface</th><th>Manual check</th></tr><tr><td>Operational guidance reflects current repo state.</td><td>Needs Verification</td><td>Docs / Code / Running app</td><td>Compare the page against current repo docs and screens.</td></tr><tr><td>Public KB claims are backed by implementation checks.</td><td>Implemented</td><td>BookStack process</td><td>Each article includes an implementation status table.</td></tr></tbody></table>

## Verification checklist

- Check source docs.
- Check running local app if needed.
- Update status labels after verification.
- Link related public help pages.

## Gaps / notes

- This is a living internal book and should be revised as implementation changes.
- Some pages intentionally summarize runbooks instead of replacing them.

# Mobile app integration map

## Public help

Map attendee, organizer, and scanner app responsibilities to backend/API behavior.

## Operating guidance

This is an internal implementation document. It should help LinkUp decide what is true, what is missing, and what needs testing next.

## Source rule

Use repo docs, running screens, and test results as source material. If sources disagree, mark the feature as **Needs Verification**.

## Implementation status

<table id="bkmrk-expected-behaviorsta"><tbody><tr><th>Expected behavior</th><th>Status</th><th>Surface</th><th>Manual check</th></tr><tr><td>Operational guidance reflects current repo state.</td><td>Needs Verification</td><td>Docs / Code / Running app</td><td>Compare the page against current repo docs and screens.</td></tr><tr><td>Public KB claims are backed by implementation checks.</td><td>Implemented</td><td>BookStack process</td><td>Each article includes an implementation status table.</td></tr></tbody></table>

## Verification checklist

- Check source docs.
- Check running local app if needed.
- Update status labels after verification.
- Link related public help pages.

## Gaps / notes

- This is a living internal book and should be revised as implementation changes.
- Some pages intentionally summarize runbooks instead of replacing them.

# Frontend migration map

## Public help

Map legacy public pages, v2 Blade pages, and route wiring status.

## Operating guidance

This is an internal implementation document. It should help LinkUp decide what is true, what is missing, and what needs testing next.

## Source rule

Use repo docs, running screens, and test results as source material. If sources disagree, mark the feature as **Needs Verification**.

## Implementation status

<table id="bkmrk-expected-behaviorsta"><tbody><tr><th>Expected behavior</th><th>Status</th><th>Surface</th><th>Manual check</th></tr><tr><td>Operational guidance reflects current repo state.</td><td>Needs Verification</td><td>Docs / Code / Running app</td><td>Compare the page against current repo docs and screens.</td></tr><tr><td>Public KB claims are backed by implementation checks.</td><td>Implemented</td><td>BookStack process</td><td>Each article includes an implementation status table.</td></tr></tbody></table>

## Verification checklist

- Check source docs.
- Check running local app if needed.
- Update status labels after verification.
- Link related public help pages.

## Gaps / notes

- This is a living internal book and should be revised as implementation changes.
- Some pages intentionally summarize runbooks instead of replacing them.

# Known issues and investigation backlog

## Internal operations

Use this page to track known technical investigations and avoid overclaiming behavior in public help articles.

## Current clarified items

- **Google login email verification:** Google-created accounts are treated as verified because Google verifies the email address. No separate LinkUp verification email is sent for Google login.
- **Email and password signup:** normal accounts may require a LinkUp verification email. If the user does not click the link, the account may remain unverified.
- **Two-step checkout:** the LinkUp fee and organizer ticket payment can be separate. A ticket is issued only after both steps are confirmed.
- **Expired checkout:** expired unpaid holds should not allow a stale purchase. The buyer may need a new order if the timer expires.

## Items to keep watching

- Refund handling across provider-specific flows.
- Offline cash and bank-transfer confirmation behavior.
- Mobile app parity for checkout, tickets, and QR recovery.
- Inventory race behavior when multiple buyers attempt the last tickets.

## Publishing rule

Public help pages should describe confirmed behavior only. If behavior differs by environment, keep sandbox details in internal operations pages.

# Manual smoke test index

## Public help

Collect the manual checks needed for public site, attendee, organizer, admin, scanner, and payment flows.

## Operating guidance

This is an internal implementation document. It should help LinkUp decide what is true, what is missing, and what needs testing next.

## Source rule

Use repo docs, running screens, and test results as source material. If sources disagree, mark the feature as **Needs Verification**.

## Implementation status

<table id="bkmrk-expected-behaviorsta"><tbody><tr><th>Expected behavior</th><th>Status</th><th>Surface</th><th>Manual check</th></tr><tr><td>Operational guidance reflects current repo state.</td><td>Needs Verification</td><td>Docs / Code / Running app</td><td>Compare the page against current repo docs and screens.</td></tr><tr><td>Public KB claims are backed by implementation checks.</td><td>Implemented</td><td>BookStack process</td><td>Each article includes an implementation status table.</td></tr></tbody></table>

## Verification checklist

- Check source docs.
- Check running local app if needed.
- Update status labels after verification.
- Link related public help pages.

## Gaps / notes

- This is a living internal book and should be revised as implementation changes.
- Some pages intentionally summarize runbooks instead of replacing them.

# Configure Polar and PayPal checkout providers

## Internal operations

LinkUp two-step checkout depends on the LinkUp fee provider and the organizer payment provider.

## Polar

- Use Polar for LinkUp Ticket Services and organizer allocation or activation products.
- Use the correct environment: sandbox for staging, live for production.
- Use USD products when the checkout is USD.
- Use a custom or pay-what-you-want amount product where LinkUp must send the calculated fee amount.

## PayPal

- Use PayPal sandbox credentials on staging.
- Use PayPal live credentials only in production.
- Verify the organizer account can receive the event currency.

## Required checks

1. Confirm environment variables match the intended provider environment.
2. Confirm product IDs belong to the same Polar environment as the token.
3. Confirm PayPal client ID and secret belong to the same PayPal environment.
4. Run a small checkout before publishing or announcing paid ticket sales.

# Troubleshoot two-step checkout

## Internal operations

Use this checklist when checkout does not complete after the LinkUp fee, organizer payment, or return step.

## Polar checks

- Token is for the correct environment.
- Product ID is for the correct environment.
- Product currency matches checkout currency.
- Product type allows the app-calculated amount.
- Return URL points back to the correct LinkUp environment.

## PayPal checks

- Client ID and secret are from the same environment.
- Organizer payment settings are enabled for the event organizer.
- Return and cancel URLs point to the current environment.
- Buyer is using a valid PayPal sandbox or live funding source for that environment.

## Order checks

- Order hold has not expired.
- Inventory is still available.
- LinkUp fee status and organizer payment status are both confirmed.
- Ticket was issued after both payment steps completed.