Implementation Spike Plan

Status: Proposed next step
Date: 2026-04-16

Goal

Build the smallest real implementation that proves Brainforge can turn existing markdown source assets into fixed-layout branded PDFs that are recognizably aligned with the current Sales Assets Figma system.

This spike is not trying to solve every document shape. It should answer one question cleanly:

Can Brainforge render its first one-pager, service two-pager, comparison page, and proof-oriented case study from repo content without needing a designer to manually recompose the output in Figma?

Recommendation

Use a narrow Spike 1 implementation inside apps/platform.

Why this is the best first move:

• the Platform already contains the closest distribution surface (/marketing-assets)
• the repo is already Node and Next.js based
• no separate service is needed until rendering volume, reliability, or deployment ergonomics make it necessary
• it keeps the first feedback loop short for Platform, GTM, and Design

Recommended shape:

fixture markdown -> typed adapter -> fixed-layout HTML component tree -> server-side Chromium PDF render -> artifact review

Proposed Spike Scope

In scope

1. One real one-pager fixture.
2. One real two-page service fixture.
3. One real comparison-style fixture.
4. One real case-study fixture.
5. A small typed document model.
6. A small reusable print component set.
7. HTML output and PDF export.
8. Side-by-side review against selected Figma benchmark families.

Out of scope

1. Arbitrary markdown support.
2. WYSIWYG editing.
3. Automatic publish to brainforge-files.
4. Full case-study template family beyond one selected proof-oriented case study.
5. Background jobs, queueing, or bulk generation.
6. Generalized metadata/catalog integration in the Platform UI.

Fixture To Benchmark Mapping

Fixture A: Insurance workflow automation one-pager

Source:

• knowledge/sales/agents/service-assets/insurance-workflow-automation-one-pager.md

Closest benchmark family:

• General Services - V1 - Mar 2025

Why:

• shared one-page story arc
• strong hero + stats + services/benefits + CTA shape
• similar need for a prominent transformation narrative at the top of the page

Fixture B: Insurance broker lead intake two-pager

Source:

• knowledge/sales/marketing-assets/design-ready-copy/insurance-broker-lead-intake-2pager.md

Closest benchmark family:

• Page 1: Service Offerings - V1 - Mar 2026
• Page 2: Event Data Modeling - Page 2
• Optional supporting pattern: FAQs (1/2) and FAQs (2/2) for stacked information density and explicit page ownership

Why:

• page 1 wants hero, proof, KPI, and capability rhythm
• page 2 wants more structured content blocks and explicit bottom-of-page ownership
• the source copy is already canonical two-pager copy, so it is the best first pagination test

Fixture C: LMNT BI tool recommendation comparison asset

Source:

• knowledge/clients/lmnt/resources/lmnt_bi_tool_recommendation.md

Closest benchmark family:

• primary: Pricing Page - V1 - May 2025
• supporting density pattern: Event Data Modeling - Page 2

Why:

• the document already contains an executive recommendation, decision criteria, and a comparison matrix
• the core visual problem is side-by-side platform evaluation rather than narrative storytelling
• the pricing/comparison family is the closest existing print system match for a structured comparison asset

Fixture D: Amazon BI analytics case study

Source:

• knowledge/sales/marketing-assets/case-studies/Amazon_BI_Analytics_CaseStudy.md

Closest benchmark family:

• page 1 benchmark: General Services - V1 - Mar 2025
• page 2 benchmark: Service Offerings - V1 - Mar 2026

Why:

• it has clean frontmatter, explicit Context / Challenge / Solution / Results sections, and a compact metrics story
• it introduces proof-oriented composition, at-a-glance metadata, and tool/team callouts without requiring a fully generalized case-study system
• it is more implementation-ready than looser case-study markdown because the section boundaries are already stable

Minimum Component Inventory

The first spike should support only the components needed for the four chosen fixtures.

Page shell

• PrintPage
• PageContentFrame
• BrandStripFooter
• PageNumber

Shared header and footer

• HeroHeader
• TrustedByRow
• CtaBanner
• ContactFooter

Content blocks

• MetricCards
• BenefitGrid
• CapabilityList
• AudienceBlock
• TimelineSteps
• ProofHighlight
• ProcessSteps
• ComparisonMatrix
• RecommendationCallout
• ResultsTable
• AtGlancePanel
• TeamAndToolsStrip

Page-2 oriented structured blocks

• SectionIntro
• ThreeColumnOfferGrid
• RoadmapSteps
• FaqStack

Proposed Document Model

The first model should be typed and explicit, but narrow.

type AssetDocument = {
  documentType: 'one-pager' | 'two-pager' | 'comparison' | 'case-study'
  title: string
  subtitle?: string
  pages: AssetPage[]
  contactBlock?: ContactBlock
}
 
type AssetPage = {
  pageType:
    | 'general-one-pager'
    | 'service-page-1'
    | 'service-page-2'
    | 'comparison-page'
    | 'case-study-page-1'
    | 'case-study-page-2'
  sections: AssetSection[]
}
 
type AssetSection =
  | HeroSection
  | TrustedBySection
  | MetricSection
  | BenefitsSection
  | ProcessSection
  | CapabilitySection
  | AudienceSection
  | ProofSection
  | CtaSection
  | ComparisonSection
  | ResultsSection
  | AtGlanceSection

Implementation rule:

• do not parse directly from arbitrary headings into generic blocks
• write one adapter per fixture/archetype
• let the adapter decide which sections land on which page

Adapter Strategy

The adapters should be handwritten for the first spike.

Adapter 1

• Input: insurance-workflow-automation-one-pager.md
• Output: AssetDocument with pageType = general-one-pager

Expected mapping:

• Top Section: Visual Storytelling → HeroSection + MetricSection
• Value Proposition → short narrative block inside hero or intro section
• Benefits → BenefitGrid
• Audience → AudienceBlock
• What's Included → CapabilityList
• Process/Timeline → TimelineSteps
• Success Metrics → ProofHighlight or secondary metrics row
• Call to Action + Footer → CtaSection + ContactFooter

Adapter 2

• Input: insurance-broker-lead-intake-2pager.md
• Output: AssetDocument with service-page-1 and service-page-2

Expected mapping:

• Header → HeroHeader
• Trusted by → TrustedByRow
• KPI / metric highlight → MetricCards or ProofHighlight
• Process → ProcessSteps
• Menu of capabilities → CapabilityList or ThreeColumnOfferGrid
• Who this is for + Deliverables → AudienceBlock + structured deliverables block
• Case study highlight → ProofHighlight
• CTA + Follow-up / Let's talk → CtaBanner + ContactFooter

Page ownership rule:

• page 1 should carry hero, trust/proof, KPI, and process
• page 2 should carry capability density, audience/deliverables, proof, and CTA/footer

Adapter 3

• Input: lmnt_bi_tool_recommendation.md
• Output: AssetDocument with pageType = comparison-page

Expected mapping:

• Executive Summary → HeroSection + RecommendationCallout
• Why a March Omni Trial → short narrative block or intro section
• Pilot Scope + Success Criteria → compact capability / checklist section
• BI Platform Comparison Matrix → ComparisonMatrix
• Other Tools Considered → secondary comparison or exclusion notes block
• Recommended BI Architecture → structured recommendation stack + CTA/footer

Implementation rule:

• keep the comparison table curated and typed; do not attempt generic markdown table support in Spike 1

Adapter 4

• Input: Amazon_BI_Analytics_CaseStudy.md
• Output: AssetDocument with case-study-page-1 and case-study-page-2

Expected mapping:

• frontmatter metrics → MetricSection
• Context + Challenge → page 1 narrative structure
• Solution → primary proof/content section with tool references
• Results → ResultsTable + proof band
• Project Details → AtGlancePanel + TeamAndToolsStrip

Page ownership rule:

• page 1 should establish context, challenge, and the core solution story
• page 2 should carry results, metadata, team/tools callouts, and the closing proof/CTA treatment

Proposed Repo Shape

This should start as a server-only module inside apps/platform.

Suggested directory shape:

apps/platform/src/lib/marketingAssetPipeline/
  adapters/
    insuranceWorkflowAutomation.ts
    insuranceBrokerLeadIntake.ts
    lmntBiToolRecommendation.ts
    amazonBiAnalyticsCaseStudy.ts
  components/
    print/
  render/
    renderAssetHtml.ts
    renderAssetPdf.ts
  templates/
    generalOnePager.tsx
    serviceTwoPager.tsx
  types.ts

Why this shape:

• keeps the spike isolated from the existing asset browser
• allows server-only rendering code without polluting the client UI layer
• preserves a path to later move rendering into a job or separate service if needed

Rendering Approach

HTML

Render fixed-layout HTML first.

Requirements:

• explicit page container sized to the Figma system
• deterministic inner content frame
• no responsive behavior inside the print template
• all spacing controlled through the template system, not markdown defaults

PDF

Use server-side Chromium rendering first.

Preferred first implementation decision:

• start with a Chromium-based renderer in app code
• keep the abstraction behind renderAssetPdf() so the engine can later swap to Gotenberg if needed

The important evaluation point is not the exact package name. It is whether Brainforge can keep the rendering engine behind a small boundary while preserving HTML-first templates.

Verification Plan

The spike should be evaluated against both implementation and design criteria.

Functional checks

1. The adapter produces a stable typed document model.
2. The HTML renders consistently on repeat runs.
3. The PDF export preserves page count and content order.
4. Page 2 content does not overflow or rely on accidental browser flow.
5. Comparison rows remain readable and visually consistent without manual column tuning in Figma.
6. Case-study metadata and results blocks feel intentionally composed, not bolted onto a generic service template.

Figma fidelity checks

1. Header band feels visually equivalent to the selected benchmark family.
2. Metric block density matches the benchmark rather than looking like a web dashboard.
3. Footer and brand strip placement feel deliberate and consistent.
4. Two-page output has explicit page ownership, not arbitrary page breaks.
5. Overall section rhythm looks like a Brainforge leave-behind, not a printed webpage.
6. Comparison assets read like a Brainforge recommendation memo rather than a raw exported table.
7. Case-study assets preserve proof density without losing readability.

Operational checks

1. The spike can run locally from apps/platform without standing up another service.
2. The rendering boundary is narrow enough to move later if needed.
3. Template code is understandable by a Platform engineer without designer-specific tooling.

Exit Criteria

Spike 1 is successful if all of the following are true:

1. The one-pager fixture can be generated from repo source copy with only adapter logic and no hand-editing in the template.
2. The two-pager fixture can be generated with explicit page ownership and no broken pagination.
3. The comparison fixture can be generated with a stable, typed matrix and a clear recommendation stack.
4. The case-study fixture can be generated with proof, results, and metadata blocks that still feel native to the print system.
5. Design review says the output is close enough to the Figma family that iteration can continue in code rather than returning to manual export.
6. The team still believes apps/platform is a reasonable home for the next increment.

Decisions To Make After Spike 1

1. Whether to keep rendering inside apps/platform or move it behind a service boundary.
2. Whether publishing should also emit HTML preview artifacts alongside PDFs.
3. Whether the section schema is stable enough to formalize across more archetypes.
4. Whether advanced paged-media tooling is necessary for multi-page quality.
5. Whether the next template family should deepen comparison/case-study coverage or move into FAQ-specific pagination.

---

Last updated: 2026-04-16