Broc Engineering Partnership

Our answer to each item in Broc's technical brief, section 6, "Where help is needed." Four things to know:

• Phase 1 fixes the foundation. A pipeline instead of laptop deploys, database changes tracked in version control, every conversation traceable, and an independent review of the safety design. About 20 to 28 engineer-days, fixed scope.
• Then we stay on. One senior engineer as Broc's standing technical partner, with specialists from our team on demand, working through the open items and the roadmap in the order Broc sets.
• Two big platform decisions are made with data, not guesses. When to move compute off Vercel, and whether Broc should own its backend instead of relying on Supabase. Both decided together at the end of Phase 1.
• Everything ships through Broc's own gate. Type-check, the offline tests, and the AI evaluation harness, with paid live-model runs only on the founder's sign-off.

How the engagement works

A fixed first phase with a clear finish line, then a standing partnership.

Every ask, on one page

Fifteen items. Reference codes are used everywhere in this document.

CI/CD

Nothing reaches production without passing the tests. Nobody deploys from a laptop.

Today a change goes live when someone runs a command on their own machine. There is no record of what was checked first, and no guarantee the code in production matches the code in version control.

Broc gets

• A pipeline: every change is reviewed, tested, and built automatically before it can go live.
• A preview link for every proposed change, so the founder can try it before it ships.
• A rehearsed rollback that takes minutes, not a scramble.

Done when

• A change with a failing test cannot be merged.
• Rollback demonstrated in under five minutes.

We need

GitHub organization ownership, Vercel team access, the current environment files, and thirty minutes on today's deploy routine.

Migration tooling

Every change to the database is written down, reviewed, and applied the same way every time.

Broc's database structure is tracked by hand today. That works until the one time it doesn't, and the brief already says the team avoids the tool's own shortcut because its history isn't reliable.

Broc gets

• Database changes in version control, applied to a staging copy first, then to production automatically.
• Automated tests proving each user type can only see its own data, across all 27 tables.
• A check that warns if production ever drifts from the recorded history.

Done when

• A fresh database built from the records alone matches production exactly.
• A deliberate data-access mistake is caught by the tests before it ships.

We need

Supabase owner access, which ORM is in use, and the manual history kept so far.

Observability

Any conversation can be traced end to end, and someone is alerted before a user complains.

Broc already logs each turn and its cost. What's missing is the layer on top: a dashboard that shows how fast and how expensive things are, and an alarm when they go wrong.

Broc gets

• Dashboards for speed, cost per conversation, and how often each safety check intervenes.
• Alerts for errors, slowdowns, cost spikes, model outages, and any safety guard trip that matters.
• Real numbers to replace the brief's estimates, and the data behind the hosting decision in P1.

Done when

• Pick any conversation from the last week and see its full story in under a minute.
• A simulated model outage raises an alert within five minutes.

We need

Approval of the tracing service (free tiers should cover pilot volume) and model provider dashboard access.

Security and architecture review

A second senior engineer reads the safety design end to end and tells Broc what to fix before it grows.

The brief asks for exactly this: a human, senior perspective on the guard-and-vault design before scaling traffic or handling more sensitive data. Broc's product is built around four promises that must never be false. We test each one.

Broc gets

• A written report: every finding ranked by severity, with how to reproduce it, how to fix it, and how long the fix takes.
• Quick fixes applied during the review: web security headers, servers moved from Sydney to Tokyo, duplicate-request protection, cheaper photo serving.
• The technical inputs Broc's lawyer needs for a privacy notice, and a recommendation on handling clinic and pharmacy conversations.

Done when

• Every critical and high finding has an agreed fix or an explicitly accepted risk.
• All existing tests and the AI evaluation harness still pass after the fixes.

We need

Repository read access, a walkthrough of the guard design, and founder sign-off for any paid live-model runs the review needs.

Cleanup items

Two small items from the brief, done through the new process so it gets its first real use.

Broc gets

• The leftover unused database permission removed.
• Stale push-notification destinations cleaned up automatically on a schedule, with a number on the dashboard so they never quietly pile up again.

Done when

Both changes are merged through the gate and the stale count reads zero.

Note

The brief and the app's own service worker describe push differently. We confirm the real status first (see Before day one).

Where Broc runs

Stay on Vercel now. Measure what it really costs. Keep the exit cheap.

Vercel is the right home for a pilot: automatic previews, instant rollback, and no servers to run. Its pricing is fair today because Broc's conversations spend most of their time waiting on the AI model, which costs little compute. At much higher traffic the bill grows with request counts, memory, and bandwidth, and the app can become dependent on Vercel-only features that make leaving expensive.

Broc gets

• A cost model from real data: what a conversation costs today, and at ten and a hundred times today's traffic, on Vercel and on Google Cloud.
• A portability rule we enforce in every review, so the app can move in weeks rather than months.
• An agreed trigger for moving, and a plan for when it fires.

Done when

Broc can state its cost per conversation at ten times traffic and the exact condition under which compute moves.

Who owns the backend

We recommend Broc own its backend rather than rent it from Supabase. In stages, and not during a live pilot.

Owning the backend means Broc controls its costs, its infrastructure choices, and its authorization logic, and can move hosting freely. The reason not to do it on day one is that Broc is live, with 27 tables protected by database policies and vendor-run login. Rewriting that mid-pilot is the wrong risk. So the plan is staged: each step is useful on its own, and Broc can stop at any stage.

Broc gets

• A decision document at the end of Phase 1, using real cost and usage data, with a clear go or no-go.
• If go: a five-stage plan where the pilot never goes dark and every stage can be rolled back.

Stages

1. Database structure defined in code (Drizzle) as the source of truth. F2 does this if Drizzle is already in use.
2. All database access goes through Broc's own service layer.
3. Login behind an interface, so the provider can change without touching the product.
4. Database moved to Broc's own Postgres, with Redis added for conversation state and rate limits.
5. Database policies retired in favor of tested application-level permissions.

Reconnect handling

A dropped connection never sends the same message to the AI twice.

Today, if a traveler's phone loses signal mid-conversation and retries, the same request can reach the model again. That costs money and, worse, can produce two answers to one question.

Broc gets

• Each request carries a unique key; the server recognizes a repeat and ignores it.
• The app shows where the conversation is ("Broc is checking your message") instead of a blank screen.
• Tests for the failure cases: double tap, lost signal, and one user's key reused by another.

Done when

A scripted disconnect-and-retry produces exactly one model call, and the duplicate rate on the dashboard reads zero.

Streaming responses

Replies feel immediate, and no text appears before the safety checks have passed it.

Broc switched off word-by-word replies because they could show text before the guards had run. The right fix is in two parts: make the whole turn faster first, then show an immediate acknowledgement while the checked reply follows.

Broc gets

• Speed work first, measured on the F3 dashboard: closer servers, prompt caching, and a smaller model for the first step may make streaming unnecessary.
• If still needed: an instant "here is what I understood, checking now," then the approved reply.
• Evaluation cases proving that unchecked text can never reach the screen.

Done when

The first visible text appears in under two seconds, and no code path shows model text before the guards have passed it.

Invitation claim flow

A business claims and verifies its account on a phone, in Japanese, with nobody at Broc doing it by hand.

This is the front door of the business funnel, deferred since an earlier milestone. Until it exists, every new business is manual work for the founder.

Broc gets

• A claim link that expires and works once, with email verification and an optional extra step for clinics.
• Clear rules for transferring ownership, and an admin screen for edge cases.
• Japanese-language screens, reviewed by Broc.

Done when

An invited business completes the claim in under five minutes on a phone, and an expired or reused link fails safely with a clear message.

Safety hardening

The weekly cadence of guard fixes continues, now with a second person reading every change.

Broc's brief says this class of fix ships roughly weekly as real usage surfaces edge cases. We keep that rhythm and add what a solo founder cannot: a second pair of eyes on every change to the safety layer.

Broc gets

• Weekly triage of real edge cases, from the dashboard data, into fixes with a regression test each.
• A second reader from our team on every guard change, always.
• A monthly report: how often guards intervened, incidents, and open risks.

Done when

No guard change merges without a test and a review, and the monthly report is delivered.

Business growth tooling

Businesses sign themselves up, and reply from the app they already use: LINE.

The brief says the business inbox exists but the funnel is early. The single most useful addition is not in the brief: most small Japanese businesses already run on LINE, and asking them to watch another inbox is the hardest part of Broc's pitch.

Broc gets

• A LINE bridge: the business replies in LINE, Broc translates and checks it, the traveler sees it in their thread.
• A self-serve path from waitlist to first conversation, with every step measured.
• A Japanese landing page businesses can actually find, and a rules editor for hours, allergies, and cancellation terms.

Done when

A business goes from waitlist to first mediated conversation without Broc staff, and a LINE reply appears in the traveler's thread within seconds.

We need

A LINE Developers account and one business willing to pilot the bridge.

Native mobile apps

App Store and Play Store apps, built when there are enough users to be worth it. Not before.

Broc already installs on a phone and can send notifications as a web app. What the stores add is being found. That is worth doing once travelers come back and businesses stay, and not worth doing while the product is still proving itself. No desktop app is needed.

Broc gets

• iOS and Android apps wrapped around the existing product, with real native notifications.
• Everything the stores require: privacy labels, in-app account deletion, review readiness.
• A release process that ships a version from a single command, with staged rollout and rollback.

Done when

Both stores approve, notifications arrive on real devices, and a release ships without manual steps.

New languages and markets

A new market is mostly a business decision. The engineering is small, and it is mostly proof.

The brief says the recipient-side language handling already generalizes. Our job for each new language is to prove the safety and tone hold before any user sees it.

Broc gets

• An evaluation set for the new language, run through the same harness as Japanese.
• Tone and register rules for the new recipient language, and the app's screens in that language.
• A market-entry checklist covering hosting region, data residency, and what the lawyer needs.

Done when

The evaluation harness passes in the new language at parity with Japanese.

The all-round agent

A design brief now. Building starts when the travel product has proven itself.

The brief calls this the largest piece of new work: pointing the same engine and safety layer at everyday errands. We agree it is the direction. We also think building a second product on an engine that has not yet proven the first is the one thing to avoid.

Broc gets

• A written brief: which errands the current engine can handle unchanged, which need new safety guards, and which to build first.
• What each of Broc's four promises means for errands that involve money, calendars, or third parties.

Starts when

Travelers come back and businesses stay. Implementation is scoped separately at that point.

Tools we will use

GitHub for code and checks. Vercel to run the app for now, Google Cloud later if the numbers say so. Standard, well-supported tools everywhere else.

Defaults below, with the alternative for each. Broc can swap any of them; the plan holds either way.

How the week runs

One call a week. Everything else in writing. Every change through Broc's own gate.

• One weekly planning call with the founder; the rest asynchronous in GitHub.
• Every change goes through the gate Broc already uses: type-check, offline tests, the AI evaluation harness, then review. Paid live-model runs only on the founder's sign-off.
• Safety-layer changes always get a second reader from our team.
• Phase 1 ends with a written review and a prioritized backlog. The retainer works through it in the order Broc sets.
• A monthly report during the retainer: what shipped, safety and cost numbers, open risks, next month.
• Japanese-facing work: we write screen text in Japanese for Broc's review; conversations with businesses stay with Broc.

Before day one

Eight things we need from Broc, in the order that unblocks the rest.

1. The legal entity that signs, and confirmation that the code, domain, and hosting accounts belong to it or will.Everything we build needs an owner.
2. Access to GitHub, Vercel, Supabase, the model provider dashboard, and DNS.Needed on day one.
3. Current state: which ORM, which AI model and provider, the database region, the manual schema history, and how the evaluation harness is run.Sets the first three weeks.
4. Pilot numbers today: businesses live, active travelers, conversations per day, completed round trips, any incidents.The baseline every dashboard starts from.
5. A privacy policy and terms published or in progress with counsel, the status of the telecommunications business notification, and how clinic conversations are handled today.Before our team is publicly associated with the product.
6. Where Broc ends and PAAN's RESTO-PAAN begins, and whether any Kushinobo branches are live on Broc.Shapes the business funnel and the LINE pilot.
7. Runway and timing, so Phase 1 and the retainer are sized to what Broc can sustain.A smaller finished Phase 1 beats a larger unfinished one.
8. The real status of push notifications, since the brief and the app's code describe it differently.Decides one small item in Phase 1.

Assumptions and out of scope

Effort is an estimate until we have read the code. Pricing is on a separate sheet.

• Effort assumes the codebase matches the brief. Figures are revised, in writing, after the first week of the review.
• Pricing, weekly allocation, and response times are on the commercial sheet.
• Nothing here is legal advice. We provide technical inputs; Broc's counsel provides the documents.
• Marketing content, business onboarding conversations, and Japanese-language customer support are Broc's.
• Design work beyond the business funnel is scoped separately with our designer.
• The all-round agent is a design brief in this proposal; implementation is a separate scope once its entry criteria are met.