DocCompile - demo pack¶

This page assembles sections relevant to demos and stakeholder presentations: overview, role, architecture, decisions, roadmap, and demonstration.

Contents¶

Summary
Overview
Role and Responsibilities
Architecture and Integrations
Decisions, Trade-offs, and Risks
Roadmap and Demonstration

Summary¶

Status¶

Working SaaS with an evolving product hypothesis. The implemented foundation is a docs-as-code publisher and AI transformation service. The target direction is a professional artifact compilation platform.

Role¶

Founder: product owner, system architect, and implementation owner.

Stack¶

Client-side SPA; AWS CloudFront, private S3, API Gateway, Lambda, DynamoDB, Cognito; Terraform; GitHub Actions with OIDC; replaceable LLM provider; Paddle billing.

Exact service inventory and commercial contour details should be confirmed against the product repository.

Project value¶

For the target audience (engineers, analysts, architects, and other professionals who already work in Markdown):

turn structured Markdown, Mermaid, and architecture icons into a professional PDF without leaving a docs-as-code workflow;
keep the document in the browser by default; send content to the server only when an AI compilation is explicitly requested;
use bounded, credit-metered AI transformations instead of unbounded chat generation.

For the professional profile:

founder-led SaaS from product discovery through AWS serverless architecture, identity, billing, and operations;
a documented pivot from proprietary workspace to a processing layer;
controlled LLM execution: versioned prompts, transformation jobs, cost bounds, and a target Artifact Contract / Harness model.

What this demonstrates¶

This project demonstrates the ability to:

take a product from a working rendering engine to a commercial AWS SaaS contour;
keep architecture, cost, privacy, and AI behavior under explicit control rather than treating the LLM as the system;
change the product hypothesis when evidence shows that competing for document storage is the wrong fight;
separate what is implemented today from the Compiler / Harness direction being designed next.

Overview¶

DocCompile is a professional artifact compilation platform in progress. It started as a docs-as-code publisher and is evolving toward a processing layer that compiles messy source material into professional artifacts.

The original product formula:

Markdown
+ Mermaid
+ architecture icons
+ images
+ professional themes
-> PDF

The current product formula:

Source in. Contract satisfied. Artifact out.

The longer formulation: compile messy source material into professional artifacts that satisfy explicit contracts, remain grounded in evidence, and stay consistent across every output.

DocCompile should not compete for the place where documents live. It should compete for the moment where messy source material becomes a correct professional artifact.

Product evolution¶

Docs-as-code publisher. Portable Markdown, diagrams-as-code, professional themes, and PDF export, rendered locally in the browser.
SaaS contour. Authentication, admin control plane, credits, billing, and server-side AI transformations on AWS.
Strategic pivot. Deprioritize proprietary cloud workspace / document storage. Own the transformation, not the document.
Target Compiler platform. A Compiler is a transformation contract. A universal Harness executes that contract without per-artifact hardcoded orchestration.

Implemented vs target¶

Implemented¶

The working system includes a local-first Markdown renderer with Mermaid, architecture icons, themes, images, print layout, and PDF export; an AWS-deployed SPA and serverless backend; Cognito identity and an admin control plane; runtime / versioned prompts; credit-metered AI transformations; and a commercial contour around Paddle.

Working AI transformations currently exist for at least ADR, requirements (FR/NFR, business rules, constraints), and Resume / CV. The exact Compiler list, publication lifecycle, and billing mode (Live vs sandbox) should be confirmed against the product repository.

Target / planned¶

The next architecture is a universal Transformation Harness driven by Artifact Contracts, evidence / canonical facts, customizable output templates, Situations (multi-artifact packs), and later Patch Compile. These are not presented here as deployed behavior.

Conceptual flow¶

flowchart TB
    src["Messy source"]
    compiler["Compiler"]
    engine["Transformation engine"]
    validate["Validation / repair"]
    artifact["Professional artifact"]
    sinks["Markdown / YAML / Mermaid / PDF / Git"]

    src --> compiler
    compiler --> engine
    engine --> validate
    validate --> artifact
    artifact --> sinks

Validation, repair, Git-native sinks, and contract-driven compilation are the target Harness path. The implemented path today is local rendering plus per-transformation AI jobs.

Main actors¶

Actor	Role
Author / professional user	Writes or pastes Markdown locally; exports PDF; optionally requests an AI compilation
Admin / Super Admin	Runtime configuration, prompt versions, transformation observability, Compiler publication
Compiler	Transformation contract for one class of professional artifact
Harness	Target generic orchestration that executes a Compiler contract
LLM provider	Replaceable model implementation, not the product moat

Major capabilities¶

Capability	Status
GFM / Markdown rendering	Implemented
Mermaid and architecture icons	Implemented
Professional themes, print layout, PDF	Implemented
Local-first rendering; content stays in the browser by default	Implemented
Cognito authentication and RBAC	Implemented
Runtime / versioned prompts	Implemented
Credit-metered AI transformations	Implemented
Paddle billing contour	Implemented; Live vs sandbox to be confirmed
Transformation history / admin observability	Implemented; depth to be confirmed
Universal Harness / Artifact Contract	Target
Evidence / Canonical Fact Model	Target
Situations and Patch Compile	Target

Technology stack¶

Layer	Choice	Role
UI	Client-side SPA	Local rendering, editor, export
Delivery	CloudFront + private S3 origin / OAC	Static frontend
API	API Gateway + Lambda	Authenticated server-side operations
State	DynamoDB	Jobs, credits, runtime config, prompts
Identity	Amazon Cognito	Registration, authentication, roles
Infra	Terraform	Reproducible AWS environment
CI/CD	GitHub Actions + OIDC	Deploy without long-lived cloud credentials
Intelligence	External LLM API	Replaceable generation component
Billing	Paddle	Merchant-of-Record payments

SQS, WebSocket result notification, Step Functions, and ECS Fargate appear in the architecture direction; only currently deployed services should be treated as implemented.

Role and Responsibilities¶

My Role¶

The project is founder-led and end-to-end. I own the product hypothesis, the architecture, and the implementation.

Work included:

product discovery and positioning, including the pivot from docs-as-code publisher and workspace ideas to a processing-layer / Compiler platform;
requirements definition and constraints (local-first, credits, no proprietary document store as the core);
solution architecture and system analysis: domain model, job lifecycle, identity, billing, and AI transformation boundaries;
UX and product workflow design for local rendering versus explicit server-side compilation;
AWS architecture: CloudFront / private S3, API Gateway, Lambda, DynamoDB, Cognito, and related serverless services;
Terraform infrastructure and GitHub Actions CI/CD with OIDC;
authentication and authorization design (Cognito; USER / ADMIN / SUPER_ADMIN);
billing and credit architecture (Paddle as merchant of record; credits as compute metering);
AI transformation architecture, prompt / contract design, and runtime versioning;
observability and quality strategy (transformation history, admin control plane, target Compiler Health);
privacy and cost trade-offs;
implementation, debugging, dogfooding, and roadmap prioritization.

AI assistants were used as a development accelerator for routine implementation. Architectural decisions, product direction, data boundaries, access model, review, and deployment remained under my control.

AI Usage¶

LLMs were used to accelerate routine implementation, generate boilerplate, and iterate quickly. They were not treated as authors or owners of the system.

Kept under manual control:

requirements interpretation and product positioning;
domain modeling;
architecture decisions;
privacy and cost boundaries;
access model;
prompt / contract design;
code review and debugging;
deployment decisions;
technical documentation.

Architecture and Integrations¶

Current Architecture¶

The implemented system is a client-side SPA with a serverless AWS backend for identity, billing, configuration, and AI jobs.

Browser SPA
    -> CloudFront
    -> private S3 origin (OAC)

Authenticated / server-side operations:
Browser
    -> API Gateway
    -> Lambda
    -> DynamoDB / SQS / external services

Large document bodies are not the default backend payload. Local rendering, Mermaid, themes, assets, and PDF operations run in the browser. Content is sent to the server when the user explicitly starts an AI transformation.

AI processing uses an asynchronous job model around server-side workers and an external LLM provider. Exact use of SQS, WebSocket notifications, and polling should be confirmed against the product repository. Do not read Step Functions or ECS Fargate as currently deployed unless present in that repository.

    C4Container
    title Container Diagram for DocCompile - implemented

    Person(user, "Author")
    Person(admin, "Admin")

    System_Boundary(sys, "DocCompile") {
      Container(spa, "SPA", "Browser", "Local Markdown, Mermaid, PDF, compile UI")
      Container(cdn, "CloudFront", "CDN", "TLS, cache, OAC to private origin")
      Container(static, "Frontend origin", "S3", "Static SPA assets")
      Container(api, "API", "API Gateway + Lambda", "Jobs, credits, admin, billing hooks")
      ContainerDb(db, "State", "DynamoDB", "Jobs, credits, config, prompts")
    }

    Boundary(ext, "External", "") {
      Container_Ext(cognito, "Cognito", "Identity")
      Container_Ext(llm, "LLM provider", "Generation API")
      Container_Ext(paddle, "Paddle", "Payments")
    }

    Rel(user, spa, "Uses locally")
    Rel(admin, spa, "Admin control plane")
    Rel(spa, cdn, "Loads UI", "HTTPS")
    Rel(cdn, static, "Origin", "OAC")
    Rel(spa, cognito, "Sign-in")
    Rel(spa, api, "Authenticated calls", "HTTPS JWT")
    Rel(api, db, "Reads/writes")
    Rel(api, llm, "Transformation jobs")
    Rel(api, paddle, "Webhooks / checkout")

architecture-beta
    service front(aws:cloudfront)[CloudFront]
    service static(aws:simple-storage-service)[Private S3 origin]
    service api(aws:api-gateway)[API Gateway]
    service lambda(aws:lambda)[Lambda]
    service dynamo(aws:dynamodb)[DynamoDB]
    service cognito(aws:cognito)[Cognito]
    service browser(logos:chrome)[Browser]
    service llm(logos:openai)[LLM provider]
    service paddle(logos:webhooks)[Paddle]

    browser:T --> B:front
    front:T --> B:static
    browser:R --> L:cognito
    browser:B --> T:api
    api:R --> L:lambda
    lambda:R --> L:dynamo
    lambda:B --> T:llm
    lambda:T --> B:paddle

Infrastructure is Terraform-managed. Deploys go through GitHub Actions using OIDC rather than long-lived cloud credentials.

Integration flows¶

Local publish. The browser loads the SPA from CloudFront, renders Markdown / Mermaid locally, and exports PDF locally. No document upload.

Authenticated compile. The user signs in through Cognito, submits a transformation job through API Gateway, spends credits, and receives a result when the worker finishes. The LLM provider is an implementation detail behind that job.

Billing. Checkout and subscription / credit purchase go through Paddle. The backend trusts verified webhooks, not the browser, for paid entitlements.

Admin. Elevated roles change runtime configuration and prompt versions, inspect transformation history, and roll back published prompt configuration.

Target / Planned Architecture¶

The central future differentiator is a universal Transformation Harness. It must not contain hardcoded branches such as if Resume / if ADR / if Requirements. It executes the contract supplied by the Compiler.

Source
  ↓
Suitability
  ↓
Fact / Evidence Extraction
  ↓
Generation
  ↓
Deterministic Validation
  ↓
Semantic Checking
  ↓
Repair
  ↓
Final Validation
  ↓
Artifact

Orchestration direction:

API
  ↓
Step Functions
  ↓
generic stages / workers
  ↓
external LLM provider

flowchart TB
    api[API]
    sfn[Step Functions]
    suit[Suitability]
    gen[Generate]
    val[Deterministic validate]
    sem[Semantic check]
    repair[Bounded repair]
    fin[Finalize]
    llm[LLM provider]
    art[Artifact]

    api --> sfn
    sfn --> suit
    suit --> gen
    gen --> val
    val --> sem
    sem --> repair
    repair --> fin
    gen --> llm
    sem --> llm
    repair --> llm
    fin --> art

Harness capabilities (target): stage execution, model invocation, deterministic validators, semantic validators, structured violation reporting, bounded repair cycles, retry policies, provenance, token / cost accounting, execution tracing, safe cancellation boundaries.

Invariant: adding a new Compiler should not require changing core Harness orchestration.

Future compute split¶

Compute	When
Lambda	Lightweight / serverless stages
ECS Fargate	Heavy bounded workers (for example Chromium / deterministic publishing) when Lambda limits are insufficient
EC2 / GPU	Only if self-hosted inference or sustained workloads later justify it

Principle: serverless orchestration first; specialized compute only when the workload justifies it. EC2 and containers are not part of the documented current architecture.

Decisions, Trade-offs, and Risks¶

Key Decisions¶

Markdown as the portable source of truth¶

LLM and technical output is already Markdown. The product keeps Markdown, Mermaid, icons, and conventional assets instead of a proprietary editor format. Compatibility with Git, VS Code / Cursor, MkDocs, and ordinary Markdown tooling is a product requirement, not an export afterthought.

Client-side-first rendering¶

Professional drafts stay in the browser for render, theme, Mermaid, local assets, and PDF. Server-side processing is an explicit compile action, not the default path.

Terraform-managed AWS infrastructure¶

A single-person operation needs a rebuildable environment. Production AWS is expressed in Terraform, deployed through GitHub Actions with OIDC.

Cognito for authentication¶

Managed identity for SaaS instead of a custom JWT stack. Roles (USER / ADMIN / SUPER_ADMIN) sit on top of Cognito identity.

Credits as compute metering¶

Variable-cost AI is the monetization unit. Local rendering is not degraded to force payment. Credits bound cost per user and per job.

Runtime / versioned prompts¶

AI behavior must change independently of application deploys. Prompts and related configuration live in DynamoDB-backed runtime configuration with publish / rollback.

Universal Harness vs per-Compiler logic (target)¶

Current transformations are per-artifact implementations. The target is generic orchestration that executes a Compiler contract. Adding a Compiler should not require changing Harness core logic.

Processing layer vs Cloud Workspace (strategic pivot)¶

Proprietary document storage and workspace features are deprioritized. DocCompile owns compilation, not the place where documents live.

Architectural Trade-offs¶

1. Markdown as the portable source of truth¶

Context¶

LLMs and engineers already produce Markdown. A proprietary canvas would capture lock-in and break Git-native workflows.

Decision¶

Keep GFM / Markdown, Mermaid, Iconify-compatible icons, YAML front matter, and conventional asset links as the working representation.

Rejected alternatives¶

WYSIWYG Word-like format; Notion-style blocks as the source of truth.

Rationale¶

Portable standards lower switching cost, match the author's existing tools, and keep diagrams-as-code in the same file as the text.

Trade-offs¶

Print/PDF fidelity is harder than in InDesign or Word.
Users who want a block editor may bounce.
Mermaid and pagination edge cases become product work.

Compensating measures¶

Pagination hardening and professional themes on the client.
Isolate a broken diagram from the rest of the document.
Later LaTeX as an option, not a required source format.

Review trigger¶

A paying segment that cannot accept Markdown as source; or print constraints that cannot be met in the browser.

2. Client-side-first rendering instead of a server-side editor¶

Context¶

Drafts include unpublished architecture, requirements, and personal career data. A mandatory upload-to-preview path would fight the privacy position and raise baseline cost.

Decision¶

The browser renders and exports locally. The server is used when the user requests compilation, billing, or admin operations.

Rejected alternatives¶

Server-side rendering pipeline as the only path; storing every document in a cloud workspace to enable preview.

Rationale¶

Privacy by default, low idle cost, and no document database as a prerequisite for publishing.

Trade-offs¶

Server-side capabilities require an explicit upload / compile.
Browser CPU and print CSS become first-class constraints.
Cross-device document sync is not a platform feature.

Compensating measures¶

Clear UI boundary between local export and AI compile.
Credits and identity only on the server path.
Target Git / CLI sinks instead of a proprietary store.

Review trigger¶

Need for server-side Chromium pagination at a quality the browser cannot meet; then a bounded Fargate worker, not a default editor backend.

3. Terraform-managed AWS instead of console or CDK¶

Context¶

Founder-led operations need a reproducible environment and cheap disaster recovery of infrastructure, not a unique snowflake account.

Decision¶

AWS production topology is Terraform.

Rejected alternatives¶

Click-ops console; AWS CDK; Pulumi.

Rationale¶

Declarative infra matches the rest of the docs-as-code posture. Terraform is sufficient for this serverless topology.

Trade-offs¶

Terraform state and blast-radius discipline are operational duties.
CDK might map more naturally to some AWS APIs.
Drift still has to be watched.

Compensating measures¶

GitHub Actions apply with OIDC.
Least-privilege IAM in the same codebase.
No long-lived deploy keys in CI.

Review trigger¶

Team growth that needs a different IaC standard; or AWS features that Terraform cannot express cleanly.

4. Cognito for authentication¶

Context¶

SaaS needs registration, session, and roles without building a custom identity platform.

Decision¶

Amazon Cognito as the identity provider for authenticated routes.

Rejected alternatives¶

Auth0; custom JWT issuance; Firebase Auth.

Rationale¶

Stays inside the AWS account, integrates with API Gateway authorizers, and avoids another vendor for a small product.

Trade-offs¶

Cognito UX and quota limits are AWS's.
Hosted UI constraints versus a fully custom login.
Multi-region identity is not free.

Compensating measures¶

RBAC enforced again in the backend, not only in the token.
Local features remain usable without sign-in.

Review trigger¶

Identity requirements Cognito cannot meet (enterprise IdP complexity, specific compliance packaging) at a price that justifies Auth0 or a dedicated IdP.

5. Credits as compute metering¶

Context¶

LLM calls have variable cost. Charging for PDF export would tax the free local foundation and invite a worse product.

Decision¶

Credits meter AI / compute-heavy operations. Local creation and publishing stay capable without credits.

Rejected alternatives¶

Subscription-only with unlimited AI; per-PDF pricing; hiding rendering quality behind a paywall.

Rationale¶

Aligns price with actual provider cost. Preserves the publishing last mile as a trustworthy free/local path.

Trade-offs¶

Credit UX is harder than a flat subscription.
Users may under-use AI if packs are confusing.
Does not by itself prevent quality problems.

Compensating measures¶

Job-level cost accounting.
Rate limits and failure timeouts.
Paddle as merchant of record so tax/payment machinery is not built in-house.

Review trigger¶

A segment that only wants simple subscription AI; or provider pricing that makes packs unexplainable.

6. Runtime / versioned prompts instead of hardcoded AI behavior¶

Context¶

Compilation quality will change weekly. Redeploying the SPA or Lambdas to tweak a prompt is the wrong release coupling.

Decision¶

Prompts and related runtime configuration are versioned server-side, with publish and rollback.

Rejected alternatives¶

Prompts hardcoded in application builds; one global unversioned prompt blob.

Rationale¶

Separates model behavior releases from application releases. Enables INTERNAL testing before PUBLIC.

Trade-offs¶

Runtime config becomes a production surface that needs access control.
Prompt/code skew if the application cannot execute an old contract.
Operators can ship a bad prompt quickly.

Compensating measures¶

ADMIN / SUPER_ADMIN only.
Rollback path.
Target INTERNAL -> PUBLIC Compiler lifecycle.

Review trigger¶

Compiler contracts become code-defined artifacts whose prompts are only parameters; then config and contract versioning must stay aligned.

7. Universal Harness vs per-Compiler workflow logic (target)¶

Context¶

Working transformations exist as per-type implementations. That does not scale to many Compilers, Situations, or Patch Compile.

Decision¶

Evolve toward a generic Harness that executes Compiler-supplied contracts. Prefer Step Functions for bounded multi-stage orchestration over an autonomous agent graph.

Rejected alternatives¶

Keep per-Compiler hardcoded orchestration indefinitely; LangGraph-style agent routing as the default.

Rationale¶

The planned Harness is bounded, deterministic-first orchestration with optional semantic checks. An agent framework is optional only if routing becomes genuinely model-driven.

Trade-offs¶

Migration cost from current per-type jobs.
Step Functions operational complexity.
Risk of building a framework before 2–3 Compilers are actually good.

Compensating measures¶

Start with a small set of reference Compilers.
Deterministic checks where possible; explicit failure instead of invented output.
LangGraph remains a later option, not the current target core.

Review trigger¶

Routing becomes open-ended and model-driven; or Step Functions prove a poor fit for the stage graph.

8. Processing layer vs Cloud Workspace¶

Context¶

The earlier expansion path was proprietary cloud storage, workspace, and a broader editor. That competes with tools users already have.

Decision¶

Deprioritize proprietary document storage. Own the transformation. Persist to local files, downloads, Git, CLI, and later APIs.

Rejected alternatives¶

Full Notion-like workspace as the product center.

Rationale¶

Lower switching cost, better fit for technical workflows, and a cleaner privacy story.

Trade-offs¶

No default cross-device document cloud.
Harder to show "all your docs in DocCompile".
Integrations become more important than an internal file tree.

Compensating measures¶

Strong local/Git-native direction on the roadmap.
Compile as an explicit, valuable moment rather than a place to live.

Review trigger¶

A B2B buyer that will not adopt without a hosted workspace; then a workspace would be an integration, not the core Compiler engine.

Risks¶

Risk	Why it matters	Mitigation
Transformation quality may not beat a good LLM prompt by enough	Users will not pay for a thin wrapper	Reference-quality Compilers first; contracts and validators, not prompt theatre
Semantic validation becomes validation theatre	False trust	Separate deterministic checks from probabilistic ones; never claim "AI verified"
Compiler-specific domain work scales poorly	Founder bandwidth	Small Compiler set; Harness invariants; INTERNAL -> PUBLIC
Multi-artifact Situations drift	Contradictory packs	Canonical facts and cross-artifact checks (target)
Patch Compile is hard	Brownfield is the real job	Treat as later epoch; depends on identity, facts, contracts, diffs
Cold start for eval datasets	No Compiler Health	Dogfood, outcome signals, local edit-distance buckets
Provider behavior and pricing change	Cost and quality shocks	Replaceable LLM; credits; versioned prompts
Technical audience resists SaaS lock-in	Distribution	Local/Git-native path; Markdown remains portable
Distribution	Product risk independent of architecture	Dogfooding, narrow Compilers, clear demo artifacts

Roadmap and Demonstration¶

Implemented¶

The working foundation, as described in product materials (confirm against the product repository before treating any line as a hard inventory):

Markdown / GFM renderer;
Mermaid and architecture icons;
professional themes, images/assets, print layout, PDF, pagination hardening;
local-first rendering in a client-side SPA;
AWS delivery (CloudFront, private S3 / OAC);
Terraform and GitHub Actions with OIDC;
Cognito authentication and admin control plane with USER / ADMIN / SUPER_ADMIN;
runtime configuration and versioned prompts with publish / rollback;
AI transformations for at least ADR, requirements (FR/NFR, business rules / constraints), and Resume / CV;
credits / cost controls and a Paddle billing contour;
transformation history and admin observability.

Not claimed as implemented: Step Functions Harness, ECS Fargate workers, Evidence / Canonical Fact Model, Situations, Patch Compile, GitHub App / CLI as a shipped workflow.

Current / next focus¶

Epoch numbers are provisional. Prefer the product repository if it has a newer roadmap.

Epoch	Focus	Status
-	Renderer, SaaS contour, first AI transformations, credits / Paddle	Implemented
E22	Product and Compiler quality telemetry; Compiler publication lifecycle (PUBLIC / INTERNAL / DISABLED)	Next
E23	Universal Transformation Harness; Artifact Contract	Planned
E24	Evidence / Canonical Fact Model	Planned
E25	Compiler specification; custom output templates	Planned
E26	Reference-quality Requirements Compiler	Planned
E27	API Contract Compiler; Mermaid quality engine	Planned
E28	Page-accurate publishing; Resume Compiler hardening	Planned
E29	CLI / Git-native workflow	Planned
E30	Situation engine	Planned
E31	First Situation packs	Planned
E32	Patch Compile	Planned
E33	Organization rules / custom validators	Planned
E34	GitHub App / CI integration	Planned

Screenshots and Demo¶

Screenshots are not fabricated in this pack. Add verified assets under docs/assets/doccompile/ when they exist in the product repository. Recommended set:

editor_main.png - main editor / compiler interface;
mermaid_document.png - document with Mermaid and architecture icons;
transformation_before_after.png - AI transformation input vs output;
admin_history.png - admin transformation history / observability.

Architecture is documented as diagrams in Architecture and Integrations rather than a static PNG.

Live URL, sample requests, and GIFs should be linked here only after they are confirmed.

What this project demonstrates¶

This project demonstrates the ability to:

ship a local-first publishing engine and a serverless AWS SaaS contour as one product;
meter AI as a bounded system (jobs, credits, versioned prompts) rather than an unbounded chat;
reverse a workspace hypothesis when it competes with the user's existing document home;
design the next architecture (Compiler, Harness, Artifact Contract) without presenting it as already deployed.