Summary
📚 Pilotflow Pre-Launch Series
- The $50,000 Gmail Add-on Myth
- Gmail OAuth Scopes Decoded
- Pre-Development Codebase Review ← you are here
- Legal Documents for Gmail Add-ons in 15 Minutes — March 20
In the previous post, I mapped Pilotflow’s OAuth scopes and established the Testing Status launch strategy. The scope decision was made. Now: write the code.
Except — I didn’t start writing code. I started reading it.
Why Reading Before Writing
The Pilotflow repository had been started previously by another team member and existed in a partially-built state. Before adding anything new, the right move was to understand what was already there.
This felt slower. It was actually faster.
The systematic review of the existing codebase — before writing a single line of new production code — surfaced three findings that would have been far more painful to discover after building on top of them.
What the Review Covered
The analysis had three parts:
-
Branch comparison — The main branch and a secondary development branch (
backup-code-20260202) had diverged significantly. Understanding what existed in each was essential before deciding where to build. -
Feature inventory — What functionality already existed? What was complete? What was half-built?
-
Flow tracing — For each core workflow, trace the execution path end-to-end and identify points where assumptions could break.
Finding 1: The Branches Had Grown Apart
The main branch contained one OAuth scope and basic email labeling functionality.
The development branch contained 4,146 additional lines: an email processor with forwarding and batch actions, a server utilities module, a full dashboard UI, and an end-to-end test framework. It also used seven OAuth scopes versus one on main.
Neither branch was “right.” But they needed to be understood before the merge strategy could be decided — because merging blindly would have introduced either regression (losing development branch features) or scope bloat (requesting permissions for features not yet in use).
Lesson: Before any non-trivial development starts, know the state of every active branch. Don’t assume main reflects the full project.
Finding 2: A Hidden Reprocessing Bug
The core of Pilotflow is its processing engine: scan the inbox, apply rules to matching emails, label processed messages to avoid reprocessing them.
The label used was pilotflow-processed. The logic checked whether this label was present before processing any email.
The bug: replies create new messages in the same thread. When someone replies to a Pilotflow-processed email, the reply arrives as a new message — without the pilotflow-processed label. Pilotflow then scans the thread again, encounters the unlabeled reply, and processes the entire thread — including the original message it had already handled.
This wasn’t obvious from reading the feature code. It was only visible when tracing the full lifecycle: email arrives → processed and labeled → reply arrives → thread re-examined.
The fix is architectural: track processed thread IDs, not just message IDs. Once a thread has been processed, skip it entirely on subsequent scans regardless of new messages arriving.
Finding this before building the batch-action features saved considerable debugging time. The batch-action code would have inherited the same flaw — and made it much harder to isolate.
Finding 3: The Notiwise Framework Was Reusable
This was the positive finding. A previous project (Notiwise, a Google Workspace calendar add-on) had produced a 12-phase launch framework: a standardized checklist covering OAuth scope selection, legal document templates, OAuth consent screen configuration, demo video structure, and marketplace submission.
Pilotflow’s launch path was structurally identical to Notiwise’s. The research, the decisions, the documents — all of it had been done once and carefully documented. Using that framework for Pilotflow’s launch planning saved an estimated 8–12 hours of re-figuring the same questions from scratch.
This is what compound interest looks like in software development: a thorough investment in documenting process the first time pays dividends on every subsequent project that follows the same shape.
The Architecture Decision
With the codebase review complete, the architecture decision was clear:
- Merge the development branch — the features were worth including, the scope additions were justified
- Fix the reprocessing bug — track thread IDs, not just message IDs, to prevent duplicate processing
- Use all 7 scopes with Testing Status — not scope-reduced, not CASA-ready yet; validated and shipped first
The pre-development phase cost one focused day. It prevented at least three compounding problems from being built into the foundation.
A Simple Pre-Development Checklist
For any project where you’re building on existing code:
- Read every active branch — don’t assume main is complete
- Inventory existing features (complete vs. partial vs. abandoned)
- Trace core workflows end-to-end before extending them
- Look for what’s missing from the feature, not just what’s present
- Search for reusable frameworks from similar past projects
Key Takeaways
- Pre-development codebase analysis finds bugs that new features will inherit — at a fraction of the cost of finding them post-implementation.
- Branch divergence is a silent risk. Know the state of every branch before choosing where to build.
- Process documentation from previous projects is an asset. Reuse it explicitly, not accidentally.
What’s Next
With the codebase understood and the architecture decided, the next step was making the project legally publishable: Privacy Policy and Terms of Service. Both required by Google before the OAuth consent screen could be configured. Both completed in 15 minutes using templates from Notiwise.
→ Next: Legal Documents for Gmail Add-ons in 15 Minutes
← Previous: Gmail OAuth Scopes Decoded
— Kékéli
