User Flows
This page documents the primary user journeys through Bloomberry. These flows describe the intended sequence of actions for key use cases.
Sign up flow
1
Visit sign-up page
User arrives at /sign-up via marketing site, referral link, or direct URL
2
Authenticate
User signs up with Google OAuth or email + password. Email requires verification.
3
Account created
Clerk creates user record; webhook fires to backend to create Supabase profile, initialize Starter plan, and create empty voice profile
4
Redirect to Writer
User lands on /writer — the primary product interface. A Spotlight Module shows onboarding prompts.
5
Onboarding prompts shown
Spotlight carousel shows: Train your voice, Connect accounts, explore features
Generate content flow
1
Enter concept
User types a concept, idea, or rough notes into the Writer text area
2
Select formats
User selects one or more output formats (LinkedIn, X, Blog, Image, Infographic, Carousel)
3
Select style
User picks writing style: Polished, Natural, or Punchy
4
Hit Generate
Frontend calls POST /api/writer/generate-stream — SSE stream opens, content appears in real-time
5
Review output
Generated content appears in format tabs. User reads and evaluates.
6
Refine via chat
User types refinement instructions in chat box below output. AI updates the post preserving voice.
7
Save or publish
User saves to session history, copies, or clicks Schedule to publish
Connect accounts flow
1
Open Settings
User opens Settings → Integrations
2
Click Connect
User clicks Connect next to LinkedIn or X
3
OAuth redirect
Backend generates OAuth URL → User is redirected to platform login
4
Authorize
User authorizes Bloomberry on the platform's screen
5
Callback received
Platform redirects back to /api/connections/:platform/callback with code
6
Token stored
Backend exchanges code for access token, encrypts, stores in social_connections
7
Connected
User sees connected status in Integrations settings
Schedule post flow
1
Generate or select content
User generates content or opens a saved session
2
Click Schedule
Schedule button appears below generated output
3
Select platform
User selects which connected account to post to
4
Choose time
User picks a specific time, or 'Add to queue' to auto-schedule at next default slot
5
Confirm
POST /api/scheduler/posts — record created with status: pending
6
Auto-publish
At scheduled time, cron job picks up pending posts and publishes via platform API
7
Status update
Post status updated to published or failed. User notified on failure.
Train voice flow
1
Open AI Voice settings
User goes to Settings → AI Voice → Voice Training
2
Add samples
User pastes writing samples (min 3, 500 words total) or uploads PDF/DOCX
3
Click Analyze
Frontend calls POST /api/voice/analyze
4
Processing
Backend processes samples, extracts linguistic patterns, stores fingerprint in user_voice_profiles
5
Voice active
All future generations use the voice fingerprint automatically
Upgrade flow
1
Hit limit or choose to upgrade
User receives usage warning, hits chat limit, or proactively wants more features
2
Click upgrade
User clicks upgrade button (in usage indicator or from Settings → System → Usage)
3
Checkout session
POST /api/billing/checkout creates a Stripe checkout session
4
Payment
User completes payment on Stripe's checkout page
5
Webhook
Stripe sends checkout.session.completed webhook to POST /api/billing/webhook
6
Plan activated
Backend updates user's plan to Pro in database. Limits immediately lifted.
7
Confirmation
User redirected back to Bloomberry with success message
State transitions
Each flow is designed to handle interruption. If a user drops out mid-flow (e.g., closes the OAuth popup), the state is safely recovered — no partial records or broken connections.