Brainforge Knowledge

architecture-evaluation

7 min read

Architecture Evaluation Plan

Status: Active
Date: 2026-04-16

Evaluation Goal

Choose the lightest architecture that can reliably generate:

  • high-quality one-pagers from Brainforge markdown assets
  • polished multi-page PDFs when pagination and layout matter
  • outputs that fit the current GitHub-backed Platform asset workflow
  • layouts that stay recognizably inside Brainforge’s existing Figma print system

Evaluation Criteria

Every architecture should be scored against these Brainforge-specific criteria:

  1. Authoring fit - Works well with existing markdown and design-ready copy.
  2. Template reuse - Supports reusable archetypes like one-pager, service two-pager, case study, and leave-behind.
  3. Brand fidelity - Handles typography, spacing, color, imagery, and layout predictably.
  4. Figma fidelity - Can reproduce the current print-first layout language used in the Sales Assets Figma file.
  5. Pagination quality - Handles headers, footers, page breaks, and multi-page flow.
  6. Platform fit - Fits Brainforge’s Node and Platform workflow with minimal operational sprawl.
  7. Publish fit - Can publish cleanly into the existing GitHub-backed asset library.
  8. Iteration speed - Fast for GTM, Sales Engineering, and design to refine.
  9. Complexity - Low operational and implementation burden relative to value.

Shortlist

Option A: HTML templates + Puppeteer

Shape: markdown/structured source -> HTML template -> Puppeteer PDF render

Why test it:

  • Best baseline fit for the current repo and team skill set.
  • Preserves HTML/CSS flexibility for branded layouts.
  • Likely the fastest path to a working first archetype.

What to validate:

  • one-pager visual quality
  • image handling and fonts
  • multi-page page breaks
  • PDF generation speed and deployment shape

Initial view: Most likely default recommendation.

Option B: HTML templates + Gotenberg

Shape: markdown/structured source -> HTML template -> Gotenberg render service

Why test it:

  • Good comparison against app-embedded rendering.
  • Useful if Brainforge wants a clean document-conversion service boundary.

What to validate:

  • service overhead versus direct Puppeteer
  • local/dev/deploy ergonomics
  • output parity with Option A

Initial view: Strong fallback if Brainforge prefers rendering as infrastructure.

Option C: HTML templates + page-aware print layer

Shape: markdown/structured source -> HTML template + Paged.js or Vivliostyle -> PDF render

Why test it:

  • Best candidate when multi-page polish becomes a real requirement.
  • Keeps the HTML-first baseline while improving paged-media behavior.

What to validate:

  • control of page breaks, running headers, and footnotes
  • complexity overhead versus baseline HTML rendering
  • whether the added layout quality is noticeable on Brainforge asset types

Initial view: Likely a second-step enhancement, not the first implementation.

Option D: React PDF

Shape: structured source -> React document components -> PDF

Why test it:

  • Useful as a contrast option if Brainforge wants document rendering fully inside a React component model.

What to validate:

  • whether authoring friction increases
  • whether design iteration is faster or slower than HTML/CSS
  • how much reuse is possible across web preview and PDF output

Initial view: Worth contrasting, but not the leading fit.

Deprioritized For Now

Typst

Reason to defer:

  • strong system, but introduces a separate authoring language too early

pdfme

Reason to defer:

  • more attractive for structured forms than polished narrative marketing assets
  1. Build one real Brainforge one-pager in Option A.
  2. Build the same asset in Option B only if service-bound rendering needs validation.
  3. Build one multi-page leave-behind in Option C if pagination quality is not good enough in Option A.
  4. Use Option D only as a contrast path if the team wants to pressure-test component-authored documents.

Suggested Test Inputs

  • knowledge/sales/marketing-assets/design-ready-copy/insurance-broker-lead-intake-2pager.md
  • knowledge/sales/agents/service-assets/insurance-workflow-automation-one-pager.md
  • knowledge/clients/lmnt/resources/lmnt_bi_tool_recommendation.md
  • knowledge/sales/marketing-assets/case-studies/Amazon_BI_Analytics_CaseStudy.md

These cover single-page, multi-page, comparison-heavy, and proof-oriented document shapes.

Selected Evaluation Fixtures

Use these as the first concrete fixtures for the spike:

Fixture 1: One-pager source

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

Why this is a good first fixture:

  • already structured around a one-pager flow
  • includes explicit top-section storytelling, stats, benefits, CTA, and footer
  • pressure-tests whether the renderer can normalize narrative markdown plus design guidance

Fixture 2: Multi-page service asset

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

Why this is a good second fixture:

  • already aligned to the current design-ready-copy workflow
  • has clear section boundaries and copy-only content
  • pressure-tests pagination, section rhythm, and designer handoff expectations

Fixture 3: Comparison input

knowledge/clients/lmnt/resources/lmnt_bi_tool_recommendation.md

Why this is a good third fixture:

  • contains a real executive recommendation plus a comparison matrix
  • pressure-tests whether the renderer can handle comparison-heavy layouts inside the existing print system
  • maps naturally to the Figma comparison and pricing family rather than generic narrative pages

Fixture 4: Case study input

Preferred first pass:

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

Optional contrast fixture:

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

Why these are useful:

  • Amazon_BI_Analytics_CaseStudy.md includes frontmatter, stable section boundaries, metrics, project metadata, and image placeholder patterns
  • UrbanStems_BI_Cleanup_CaseStudy.md is a strong BI-governance contrast if Brainforge wants a second case-study proof shape after the first implementation

Initial Section Contract

The first renderer should not try to support arbitrary markdown. It should normalize source docs into a small section contract that covers Brainforge’s current archetypes.

Core fields

  • documentType - one-pager, two-pager, comparison, case-study, or leave-behind
  • title
  • subtitle
  • audience
  • cta
  • contactBlock

Reusable sections

  • hero : Headline, subheadline, optional visual intent, optional key metrics.
  • stats : Array of short metric cards with value, label, and optional note.
  • valueProposition : Short narrative section describing the transformation.
  • benefits : Bullet or card list of outcome-oriented benefits.
  • process : Ordered steps or phases.
  • deliverables : Included outputs or capabilities.
  • audienceFit : Who the document is for.
  • caseStudyHighlight : Short proof block, quote, or result summary.
  • results : Metrics or outcome summary for case-study-style documents.
  • comparison : Curated comparison matrix or recommendation table with typed rows and columns.
  • footer : Brand and contact information.

Normalization rule for the first spike

For the first prototype, map source markdown into this contract with a thin adapter per archetype instead of trying to invent a universal parser. That keeps the spike small and lets Brainforge learn which section shapes are actually stable.

Template implication

The first branded HTML template should support:

  • one strong hero band
  • 2 to 4 metric cards
  • alternating narrative and list sections
  • an optional comparison table with constrained columns
  • optional proof or case-study band
  • consistent CTA and footer treatment

It should also be compared directly against the current Figma compositions rather than evaluated in isolation.

Figma-Derived Constraints

The template spike should assume the following constraints are first-class requirements, not polish items:

  1. Fixed portrait page geometry (2550 x 3300 in the current design system).
  2. Consistent inner content frame (x=100, width=2350).
  3. Reusable header/footer system instead of per-page ad hoc layout.
  4. Deterministic multi-page boundaries for assets such as FAQs (1/2) and Event Data Modeling - Page 1/Page 2.
  5. Reusable component families for:
    • hero/header
    • footer / CTA banner
    • successes metrics
    • service cards
    • roadmap steps
    • FAQ rows
    • pricing / comparison tables

Implication: Option A should not be prototyped as a generic markdown-to-print stylesheet. It should be prototyped as structured content mapped into a small set of fixed-layout HTML components.

Benchmark Families

The first spike should judge fidelity against these Figma families, even when the source copy comes from repo markdown fixtures:

  • General one-pager benchmark: General Services - V1 - Mar 2025
  • Offerings / deep-dive benchmark: Service Offerings - V1 - Mar 2026
  • Pricing benchmark: Pricing Page - V1 - May 2025
  • FAQ benchmark: FAQs (1/2) and FAQs (2/2)
  • Multi-page roadmap benchmark: Event Data Modeling - Page 1 and Event Data Modeling - Page 2

These are useful because they cover the main asset families Brainforge appears to actually ship, not just the markdown inputs that happen to exist in-repo.

First Spike Recommendation

The first implementation should be intentionally narrow:

  1. Build inside apps/platform, not a separate service.
  2. Support four fixtures:
    • insurance-workflow-automation-one-pager.md
    • insurance-broker-lead-intake-2pager.md
    • lmnt_bi_tool_recommendation.md
    • Amazon_BI_Analytics_CaseStudy.md
  3. Use one handwritten adapter per fixture.
  4. Keep the comparison matrix and case-study metadata typed and curated rather than adding generic markdown parsing.
  5. Render fixed-layout HTML first, then export PDF through a server-side Chromium boundary.
  6. Review output directly against the mapped Figma families.

The implementation details for that spike live in implementation-spike-plan.md.

Expected Outcome

At the end of the evaluation, Brainforge should have:

  • one recommended baseline architecture
  • one clear escalation path for higher-end pagination needs
  • a documented implementation path tied to existing repo surfaces
  • confidence that the baseline can stretch across narrative, comparison, and proof-oriented asset families before the team invests in a larger renderer

Last updated: 2026-04-16

Graph View

Backlinks