Architecture

A - Forja process (5-phase flow) · last updated 2026-05-30

The end-to-end client journey at byForja, from cold prospect to monthly Run. Each box below maps to a section on this page. Owners and apps are detailed in B → G. Two distinct client profiles flow through the same funnel but diverge at Launch and Run: Artist (transformation loop) and Pilot (graduation escalator). See Doctrine §3 + §7 + §18.

B - Sourcing phase · last updated 2026-05-30

Owners: AL (main, manual scrape + qualification), Claude Code (sourcing agent - to spawn, see task #11).

Apps: Instagram (manual + scrape), byforja.com inbound contact form, Notion DB Outreach Prospects.

Sub-actions

• Scrape jackpots - Instagram artisan/artist accounts matching ICP signals (craft, scale, market).
• Filter ICP / anti-ICP - apply Doctrine §3 (artist/artisan/commerce) and §13 (stories-feed dealbreaker).
• Score - magnitude × market × revenue. Output: row in DB Outreach Prospects with profile, score, source.
• Inbound triage - leads landing on byforja.com routed by domain (forja.com / byforja.com) and signal.

Outputs

• Row in DB Outreach Prospects with columns Profil + Source recommandation (added in red flag #5).
• Status: Sourced.

Partial Manual scrape in place. Sourcing agent (task #11) not yet written.

C - Qualification phase · last updated 2026-05-30

Owners: AL.

Goal: detect the client profile (Artist or Pilot) and confirm fit with byForja ICP before opening outreach.

Profile detection

• Artist - practice-first, transformation loop in Run. Output value = captured + recaptured artistic identity. Long form, identity-driven.
• Pilot - system-first, graduation escalator in Run. Output value = layered ops (tags → descriptions → titles → planning → fignolage). Process-driven.

Profile detection is decisive: it dictates the Closing pitch, the Launch checkpoints emphasis, and the Run cadence. See Doctrine §3.

ICP signals

• Real craft / artistic practice (no resell, no dropship).
• Existing revenue stream (€2k-€20k/mo typical band - see Pricing doctrine).
• Active social presence with at least one usable channel.
• French market or French-speaking diaspora (current ops scope).

Stories-feed dealbreaker (Doctrine §13)

If the prospect posts only Stories and zero Feed, decline - byForja delivery loop relies on Feed gravity. Doctrine §13 locked.

DB columns used

• Profil - Artiste | Pilote | Hybride | À qualifier.
• Source recommandation - who referred the lead (used in routing + scoring).

Done Columns shipped 2026-05-30 (red flag #5).

D - Outreach phase · last updated 2026-05-30

Owners: AL + Fred (intro for architect lead, AL does not cold-contact - see task #8 / red flag #8).

Apps: Loom (video), Brevo (email cadence), Notion DB Outreach Prospects (status tracking).

Sequence

1. Loom < 90 sec - personalized intro, recorded from a static template + 3 prospect-specific hooks.
2. Email send - Loom link + 2 lines of context. Subject: bare, no clickbait.
3. Follow-up sequence - D+3, D+7, D+14. Three touches max. After D+14: archived as No reply.
4. Reply handling - book Cal.com 45 min event (offensive-digitale) directly in reply.

DB Outreach status mapping

• Sourced → row exists, not yet contacted.
• Loom sent → first touch out.
• Follow-up 1 / Follow-up 2 / Follow-up 3.
• Booked → Cal.com event confirmed.
• No reply | Declined | Closed.

Partial Loom + Brevo wired. Outreach prompt (task #12 rehearsal) not yet rehearsed on a real jackpot.

E - Closing phase · last updated 2026-05-30

Owners: AL.

App: Cal.com event offensive-digitale - set to 45 min (was 30, updated task #14).

Pre-call

• Read prospect signals + qualification notes.
• Prepare formula hypothesis: Forja Full / Forja Complete / Forja Website / Forja Content.
• Pre-call prompt → see Checklist 45 min.

During-call (45 min)

• Diagnostic - current state, friction, ambition (12-15 min).
• Proposal - formula + scope + price (15-20 min).
• Close or commit-to-followup (10 min).

Post-call

• Update DB Outreach status → Closed | Pending | Declined.
• If Closed: trigger Launch onboarding (kickoff 1h30 booked) + contract via Yousign + Stripe payment link.
• Post-call prompt → see Checklist 45 min.

Partial 45 min event live. Closing prompts (pre/during/post) draft only - task #9.

F - Launch phase (6 weeks) · last updated 2026-05-30

Owners: AL + Claude Code (Launch agent - to spawn, task #11).

Duration: 6 weeks, kickoff + 5 weekly checkpoints. Source: Parcours client checkpoints + Doctrine §7.

Milestones

• S1 - Kickoff 1h30 - formula confirmed, scope locked, brand intake.
• S2 - Positioning doctrine - written, validated by client, archived.
• S3 - Editorial strategy + Cadre Check - channel mix, cadence, voice.
• S3-S6 - ×12 publications - produced and shipped within the 6-week window.
• S5 - Next-month plan - Run plan drafted (Artist loop or Pilot escalator).
• S6 - Handover OR Run switch - client either takes over or signs Run subscription.

Artist vs Pilot in Launch

The 6-week structure is identical, but emphasis shifts:

• Artist - S2 heavier (positioning is identity work), S3-S6 publications capture transformation moments.
• Pilot - S2 lighter (positioning is system clarity), S3-S6 publications validate the editorial machine before Run.

Outputs

• Positioning doctrine doc (Notion).
• Editorial strategy + Cadre Check (Notion).
• 12 published pieces across chosen channels.
• Run subscription signed (if Run switch) or handover deck (if handover).

Partial Process documented (Doctrine §7 + Parcours client). Launch agent (task #11) not yet written. Plan QW split Artist / Pilot in progress (task #7 closed).

G - Run phase (monthly) · last updated 2026-05-30

Owners: AL + Claude Code (Run agent - to spawn, task #11).

Cadence: monthly. Source: Doctrine §7 + §18 + Phase 1 decisions - passation spec.

Artist loop

1. Capture - record raw artistic moments (process, output, reflection).
2. Transformation - byForja team transforms raw capture into shippable pieces (post, carousel, short, longform).
3. Recapture - post-publication, recapture audience response + next-iteration material.

The loop is identity-driven: each cycle deepens the artistic positioning and accumulates a body of work over months.

Pilot escalator (graduation by layers)

The Pilot client graduates through 5 layers over months. byForja owns layer N until client owns it, then escalator moves up:

1. Tags - taxonomy + categorization automation.
2. Descriptions - caption/description templates and lift.
3. Titles - hook design and A/B logic.
4. Planning - editorial calendar ownership.
5. Fignolage - final polish + cross-channel adaptation.

Passation spec (Phase 1 decisions)

Each Run month ends with a passation review: what byForja owned, what client now owns, what next month transfers. Locked in Phase 1 decisions.

Partial Doctrine locked. Run agent (task #11) not yet written. Monthly cadence wired in Parcours client checkpoints.

H - D1 schema (byForja) · last updated 2026-05-30

Cloudflare D1 database byforja (UUID ff9f3527-bcc5-454b-88e1-c26420688b06), bound as DB on the byforja-tools Pages project.

Existing tables

• events - analytics events (page views, button clicks, conversions). Priority surface, see /analytics-map.
• error_events - JS errors + 4xx/5xx server errors.
• magic_link_tokens - auth token store (account.byforja.com magic link flow).
• pending_logins - login state machine.
• page_inventory - page registry (used by /page-flow).
• button_inventory - button registry (used by /click-analytics).

Future tables (planned)

• crm_clients - byForja client master record (mirrors DB CRM byForja).
• contracts - Yousign contract states + URLs.
• commissions - Stripe commission tracking per client.
• weekly_delivery - weekly delivery board (Launch + Run output tracking).

Partial 6 tables shipped (analytics + auth + inventory). 4 client-side tables planned for Phase 2.

I - 4-leg stool sync rules · last updated 2026-05-30

byForja production rests on a 4-leg stool. Each leg has a single source of truth. Drift between any two legs = broken production. Sync rules below mandate that any change to one leg triggers an audit of the other three.

Sync triggers

• Edit Grammar → audit Prompt + Architecture for drift (does the prompt still match? does this page still describe current state?).
• Edit Prompt → confirm Grammar still locks the intent + update Architecture if the implementation shipped.
• Edit DB schema (Outreach Prospects) → update Grammar (state machine), Prompt (which columns to write), Architecture (section H + relevant phase).
• Ship infra change → update Architecture first (this page is the artifact), then re-read Grammar + Prompt for consistency.

Full sync ruleset: Production doctrine hub - execution rules + board sync rules.

J - Pointers (Grammars / Prompts / DBs / external tools) · last updated 2026-05-30

Doctrine & hubs (Notion)

Doctrine byForja

Doctrine - sourcing / qualification / delivery / churn / sourcing

Production doctrine hub

4-leg stool sync rules, agent scopes

Execution rules

Production doctrine hub · execution sub-page

Board sync rules

Production doctrine hub · board sync sub-page

Phase 1 decisions

Locked decisions (delivery / passation / pricing / contracts)

Parcours client checkpoints

6-week Launch + monthly Run checkpoints

Checklist 45 min

Closing call checklist (pre / during / post)

HQ specifics

byForja Claude Code HQ - brand assets, infra, stack

Notion DBs

DB Outreach Prospects

Outreach pipeline - Sourcing → Closing

DB CRM byForja

CRM byForja - Active clients in Launch / Run

External tools

Cal.com

Event offensive-digitale - 45 min (Closing call).

Stripe

Forja Full / Complete / Website / Content products + Run subscriptions.

Yousign

Contract templates (Artist + Pilot variants - to import, task #16).

Brevo

Outreach email cadence + follow-up sequence.

Loom

Cold outreach videos < 90 sec.

byforja.com

Public site - inbound contact + content.

Internal admin pages

/infra-tree

Cloudflare resources tree (Pages, D1, R2, KV, Workers).

/analytics-map

Analytics source-of-truth map.

/clients

Active client list (placeholder - Phase 2).

/page-flow

byforja.com page flow.

/notion-vs-tools

Source-of-truth split per domain.

K - Maintenance · last updated 2026-05-30

This page is hand-maintained. It must be updated each time a Forja phase, DB schema, or external tool changes.

Where it lives

• Repo: ~/Projects/byforja-tools/public/architecture.html
• Live URL: https://tools.byforja.com/architecture (gated by Cloudflare Access SSO eo-team).
• Linked from: /alllinks and / (tools home).

How to edit

1. Edit public/architecture.html directly. The page uses /admin.css shared tokens + a local <style> block for arch-specific patterns (TOC, flow-diagram, status-pill, pointer-table).
2. Update the last-updated marker on every modified section.
3. Smoke test: open the live URL after deploy (CF Access will gate, expect 302 to Access if not logged in; once logged, page renders).
4. Deploy: cd ~/Projects/byforja-tools && npm run deploy:prod (per standing rule - byForja tools require explicit manual deploy).

Sync obligations (4-leg stool)

If you edit Grammar, Prompt, or DB Outreach Prospects, audit this page same turn. See section I for sync rules.

L - Status pills legend · last updated 2026-05-30

Status pills next to a section heading or sub-item indicate implementation state:

Many sections currently sit at partial because Grammars (task #9-#10) and Prompts (task #11) are not yet fully written. Expect a wave of pills moving from partial to done as Phase 2 ships.