DocCompile - SRS pack¶

This page assembles sections relevant to a software requirements specification: context and problem through security, quality, and operations.

Contents¶

Summary
Context and Problem
Goals, Requirements, and Constraints
Role and Responsibilities
System Model
Architecture and Integrations
Security, Quality, and Operations

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.

Context and Problem¶

Context¶

LLMs and technical professionals are good at producing structured text, Markdown, code, requirements, diagrams, and architecture discussions. Turning that material into a professional deliverable still often requires manual copy/paste into Word, Google Docs, or another document editor.

Diagrams are a typical fracture point. A Mermaid sequence or C4 sketch lives next to the source in Git, then has to be re-drawn or exported into a slide or Word file. The published PDF drifts from the source. The docs-as-code workflow breaks at the last mile.

The initial product therefore focused on a portable path:

portable Markdown
-> diagrams-as-code
-> professional rendering
-> PDF

Markdown remains the source of truth. The product favors portable standards: GFM / Markdown, Mermaid, Iconify-compatible architecture icons, YAML front matter, conventional image/asset links, and later potentially LaTeX. Content should stay compatible with Git / GitHub, VS Code / Cursor, MkDocs, Mermaid tooling, and ordinary Markdown tooling.

Problem¶

Two problems stacked on top of each other.

1. Publishing last mile¶

Professionals already have source material. They do not need another place to type. They need a reliable way to:

keep Markdown as the working format;
render diagrams without a proprietary canvas;
produce a professional PDF that matches the source;
avoid one broken diagram collapsing the whole document;
do this without uploading confidential drafts to a workspace they do not control.

Raw meeting notes and transcripts make the last mile more expensive. An expert still has to turn messy source into an ADR, a requirements pack, a resume, or a proposal. That work is repetitive, easy to get slightly wrong, and hard to check.

2. Workspace gravity¶

During product development, the natural SaaS expansion was a proprietary cloud document store: workspace, document management, a broader editor. That path would put DocCompile into competition for where documents live - against Notion, Confluence, GitBook, Google Docs, and the user's own Git repository.

That is the wrong fight for this product. Technical users already have a home for documents. Switching cost is high. A workspace also pulls the architecture toward persistent document storage, which conflicts with the local-first privacy position.

Strategic pivot¶

The decision:

Do not own the document. Own the transformation.

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.

Possible persistence and output sinks stay where the user already works: local files, portable packages, Git repositories, CLI, downloads, and later APIs / integrations.

The interesting engineering problem is not calling an LLM. It is building a controlled compilation system around it: contracts, evidence, validation, repair, cost bounds, and measurable quality.

Goals, Requirements, and Constraints¶

Goals and Non-Goals¶

Primary project goals¶

Preserve portable source formats (Markdown / GFM, Mermaid, conventional assets) as the working representation.
Produce professional deliverables (print layout and PDF) from that source without a proprietary editor format.
Support diagrams-as-code so architecture and sequence diagrams stay in the same file as the text.
Isolate rendering failures so one broken diagram does not break the whole document.
Keep client-side-first / local behavior for rendering, styling, local assets, and PDF operations.
Make AI usage financially bounded through credits and cost controls.
Make AI behavior configurable and versioned independently of application deploys.
Provide transformation history and admin observability for server-side AI jobs.
Evolve toward explicit Artifact Contracts: compilation succeeded, produced warnings, or failed.
Support Git-native outputs so the artifact can return to the user's existing workflow.

Out of scope¶

Not a general-purpose cloud document workspace or Notion/Confluence replacement.
Not a WYSIWYG Word clone and not a proprietary block editor as the source of truth.
Not a guarantee of hallucination-free AI output. Target checks are deterministic validation, source-grounding, and bounded repair - not an unprovable "fully verified AI" claim.
Not tied permanently to a single LLM vendor.
Does not invent missing professional facts when source evidence is absent; unresolved items should remain unresolved.
Does not include formal SLA / RTO / RPO values in this portfolio pack. Those values are Unknown / TBD unless defined in project operations artifacts.
Current architecture does not assume EC2 or always-on containers unless the product repository actually contains them.

Requirements¶

Business Requirements¶

BR-001. Portable source of truth.
The user must be able to work in Markdown (GFM), with Mermaid, architecture icons, YAML front matter, and conventional image links, without converting into a proprietary storage format.
BR-002. Professional publishing last mile.
The system must render a professional document and support PDF export from the local source, including print layout and pagination hardening.
BR-003. Local-first by default.
Rendering, styling, local assets, Mermaid, and local PDF operations must work in the browser. Document content must not leave the browser unless the user explicitly requests a server-side operation.
BR-004. Bounded AI compilation.
Server-side AI transformations must be metered (credits), cost-controlled, and attributable to a user and a transformation type.
BR-005. Configurable AI behavior.
Prompts and related runtime configuration must be versioned and publishable / rollable back without redeploying the application.
BR-006. Identity and administration.
Authenticated SaaS operations must use managed identity. An admin control plane must exist for configuration, observability, and elevated roles.
BR-007. Commercial contour.
Variable-cost intelligence is the monetization unit. Local rendering quality must not be artificially degraded to force payment.
BR-008. Artifact contract direction.
The product should evolve from "the model generated something" to an explicit compilation result: success, warnings, or failure against a Compiler contract.
BR-009. Evidence grounding direction.
Important output claims should become traceable to source evidence. Missing evidence must not be filled in silently.
BR-010. Git-native outputs.
Compiled artifacts should be able to return to local files, downloads, and later Git / CLI workflows rather than remaining locked in a proprietary store.

The public version includes a shortened requirements fragment. Internal billing amounts, prompt texts, and unpublished Compiler contracts are not disclosed.

Rules and Constraints¶

Business Rules¶

RULE-001. Local work does not require upload.
Opening, editing, rendering, and exporting a document locally must not require sending document body to the backend.
RULE-002. Server-side processing is explicit.
Content is sent to the backend only when the user invokes a server-side capability such as AI compilation.
RULE-003. Credits meter compute, not publishing quality.
Free / local capabilities provide the creation and publishing foundation. Credits pay for AI / compute-heavy operations.
RULE-004. Do not invent missing facts.
A compilation must not present unsupported professional facts as if they were present in the source. Unresolved decisions remain unresolved.
RULE-005. Compiler invariants outrank templates.
A custom output template may change artifact structure. It must not weaken Compiler guarantees (grounding, validators, repair bounds).
RULE-006. LLM provider is replaceable.
Product value sits in Compiler specifications, contracts, evidence models, validators, repair, and quality evaluation - not in one prompt or one vendor.

Constraints¶

CON-001. Founder-led, cost-sensitive serverless architecture.
Idle cost must stay low. Continuously running backends are avoided unless a workload justifies them.
CON-002. No unnecessary persistent document backend.
The system must not require proprietary cloud document storage for the core publishing path.
CON-003. No mandatory authentication for purely local / free features.
Identity is required for SaaS / AI / billing operations, not for local rendering.
CON-004. Privacy-sensitive professional content.
Drafts may include unpublished architecture, requirements, and personal career data. Default processing stays in the browser.
CON-005. AWS infrastructure must be reproducible through Terraform.
Production environment is not a click-ops console setup.
CON-006. Serverless orchestration first.
Specialized compute (for example ECS Fargate) is introduced only when Lambda boundaries are insufficient. EC2 / GPU only if future self-hosted inference or sustained workloads justify it.
CON-007. Formal operational SLAs are TBD.
This portfolio pack does not invent RTO / RPO / availability targets.

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.

System Model¶

Domain Model¶

The implemented domain is a local-first publisher plus a serverless AI transformation contour. Future Compiler / Harness concepts are listed separately and are not part of the current data model.

Implemented concepts¶

Concept	Meaning
User	Authenticated identity from Cognito
Role	USER, ADMIN, SUPER_ADMIN
Compiler	Named transformation type (historically "Template") for a class of artifact
Compiler version	Runnable revision of a Compiler / prompt configuration
Output template	Presentation structure for an artifact; currently less separated from Compiler logic than the target model
Compile run / transformation job	Asynchronous server-side AI job with status, cost, and result handling
Artifact	Generated Markdown / document output of a run
Credit account	Per-user balance for compute-heavy operations
Credit ledger entry	Attributable debit / credit of usage
Runtime configuration	Server-side settings that can change without redeploy
Prompt definition / prompt version	Versioned AI behavior with publish / rollback
Audit event	Trace of sensitive admin and transformation actions

Exact table names and attributes are omitted in the public pack.

Target / planned concepts¶

These must not be read as implemented entities:

Concept	Meaning
Artifact Contract	Objective success definition for a Compiler: parse, schema, evidence, layout constraints
Fact	Canonical extracted claim with status (asserted / uncertain / conflicting / unknown)
Evidence	Provenance pointer from a Fact back to source material
Situation	Orchestration of several Compilers around one user goal
Artifact pack	Set of related artifacts that must stay consistent
Patch Compile	Brownfield update of an existing artifact instead of full regeneration

Context diagram¶

    C4Context
    title System Context for DocCompile

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

    System(dc, "DocCompile", "Local-first publisher and AI compilation service")

    System_Ext(llm, "LLM provider", "Replaceable generation API")
    System_Ext(paddle, "Paddle", "Merchant of Record billing")
    System_Ext(idp, "Amazon Cognito", "Identity")

    Rel(author, dc, "Renders locally; requests compilation")
    Rel(admin, dc, "Config, prompts, observability")
    Rel(dc, idp, "Authenticates")
    Rel(dc, llm, "Transformation jobs")
    Rel(dc, paddle, "Checkout and webhooks")

Data Model¶

High-level implemented model¶

erDiagram
    USER ||--o{ CREDIT_ACCOUNT : holds
    USER ||--o{ TRANSFORMATION_JOB : requests
    USER ||--o{ AUDIT_EVENT : generates

    CREDIT_ACCOUNT ||--o{ CREDIT_LEDGER_ENTRY : records

    COMPILER ||--o{ COMPILER_VERSION : versions
    COMPILER_VERSION ||--o{ PROMPT_VERSION : uses
    COMPILER_VERSION ||--o{ TRANSFORMATION_JOB : executes

    RUNTIME_CONFIG ||--o{ PROMPT_VERSION : publishes

    TRANSFORMATION_JOB ||--o| ARTIFACT : produces
    TRANSFORMATION_JOB }o--|| CREDIT_LEDGER_ENTRY : meters

    USER {
        string id PK
        string role
    }

    COMPILER {
        string id PK
        string name
        string publication_state
    }

    COMPILER_VERSION {
        string id PK
        string compiler_id FK
        string status
    }

    PROMPT_VERSION {
        string id PK
        string body
        string published
    }

    TRANSFORMATION_JOB {
        string id PK
        string user_id FK
        string compiler_version_id FK
        string status
        string cost_units
    }

    ARTIFACT {
        string id PK
        string job_id FK
        string format
    }

    CREDIT_ACCOUNT {
        string id PK
        string user_id FK
        int balance
    }

    CREDIT_LEDGER_ENTRY {
        string id PK
        string account_id FK
        int delta
        string reason
    }

    RUNTIME_CONFIG {
        string id PK
        string key
        string value
    }

    AUDIT_EVENT {
        string id PK
        string actor_id FK
        string action
    }

publication_state (PUBLIC / INTERNAL / DISABLED) is a target Compiler lifecycle. If the product repository does not yet persist it, treat it as planned.

Target fact model (not implemented)¶

Fact
├── id
├── concept
├── value
├── status: asserted | uncertain | conflicting | unknown
├── evidence[]
├── source
└── provenance

Example domain facts (planned): RequirementFact, BusinessRuleFact, ConstraintFact, NfrFact, EndpointFact, EmploymentFact, SkillFact.

Key model idea¶

The implemented center of gravity is the transformation job: an explicit, metered, asynchronous compilation request. Local documents are not the system's source of truth in the cloud; they remain with the user until a job is requested.

The target center of gravity is the Compiler contract: input contract, fact schema, artifact contract, validators, repair strategies, and quality metrics. Adding a Compiler should not require changing Harness orchestration.

Compiler concept¶

A Compiler is not merely a Markdown skeleton. It is a transformation contract for a specific class of professional artifact:

Compiler
├── Input Contract
├── Fact Schema
├── Artifact Contract
├── Evidence / Grounding Rules
├── Output Template
├── Validators
├── Repair Strategies
├── Presentation Constraints
└── Quality Metrics

Architectural principle (target):

Artifact Contract
=
Compiler Invariants
+ Output Template
+ User Options
+ Organization Rules

A custom template may change artifact structure but must not weaken Compiler guarantees.

Examples of current / planned Compilers: ADR; Requirements Specification; Resume / CV; API Contract; System Design; Meeting Summary; Proposal; Executive Summary. Only the first group is claimed as working transformations today.

API contracts¶

Endpoint names in the public pack are illustrative. The backend exposes a REST/JSON API for identity-gated SaaS operations. Local rendering does not go through this API.

Capability groups:

authentication against Cognito;
transformation job submit / status / result;
credit balance and ledger;
admin runtime configuration and prompt versions;
billing webhooks from Paddle.

Security layers:

JWT from Cognito on authenticated routes;
role checks for ADMIN / SUPER_ADMIN operations;
secrets and provider keys stay server-side;
webhook routes verify Paddle signatures;
job results are restricted to the owning user except for admin observability.

Transformation job lifecycle (implemented direction)¶

submit
-> queued / running
-> succeeded | failed
-> result available to owner

Status names may differ in code. The invariant is: a job is attributable, metered, and inspectable; it is not a free-form chat session.

Error handling pattern¶

Typical statuses:

200 OK                  successful read
202 Accepted            job accepted
400 Bad Request         invalid input
401 Unauthorized        missing or invalid identity
403 Forbidden           authenticated but not allowed
404 Not Found           resource missing or not visible
409 Conflict            state conflict
429 Too Many Requests   rate or credit limit

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.

Security, Quality, and Operations¶

Security and Access Model¶

Identity¶

Authenticated SaaS operations use Amazon Cognito. Local rendering and PDF export do not require identity.

Claimed RBAC roles: USER, ADMIN, SUPER_ADMIN. Exact permission matrix should be confirmed against the product repository.

Backend authorization¶

API Gateway and Lambda enforce identity on server-side routes. Admin runtime configuration, prompt publish / rollback, and cross-user observability are restricted to elevated roles. Provider API keys and billing secrets stay server-side.

Infrastructure¶

private S3 origin for the SPA, accessed through CloudFront OAC rather than a public website bucket;
least-privilege IAM for Terraform-managed roles;
GitHub OIDC for deploys (no long-lived deployment access keys in CI);
Paddle webhook signature verification before credit or entitlement changes;
abuse and cost controls around transformation jobs (credits, rate limits).

Privacy¶

Local-first renderer: Markdown, Mermaid, styling, local assets, and local PDF operations run in the browser. There is no mandatory upload for local document work.

Server-side content processing happens only for explicitly requested capabilities such as AI compilation.

Telemetry is designed as privacy-conscious operational data, not as another document store. Edited document text should not need to be uploaded merely to calculate quality signals (for example local edit-distance buckets). Do not over-read this as a certified privacy program; legal documents should be checked separately.

Quality¶

Current¶

transformation history;
admin observability of jobs;
prompt versioning with publish / rollback;
output handling for generated artifacts;
cost / usage tracking through credits.

Depth of history, quality telemetry, and Compiler publication states (PUBLIC / INTERNAL / DISABLED) should be confirmed against the product repository.

Target¶

Artifact Contract as the definition of success;
deterministic validators (parse, schema, required sections, renderable diagrams);
semantic consistency checks (probabilistic; not "AI verified");
evidence grounding;
bounded repair loops;
Compiler Health metrics: success rate, acceptance rate, accepted unchanged, repair rate, validation failures, cost, latency.

Deterministic validation and probabilistic semantic checking are different. A second LLM pass is not treated as proof.

Quality telemetry direction¶

Signal	Meaning
Pipeline trace	Operational path of an individual Compile
Outcome signal	Accept / accept with edits / reject / regenerate / export / abandon
Aggregate Compiler Health	Metrics by Compiler / version / template

The long-term moat depends on measurable quality improvement, not on accumulating raw logs.

Non-Functional Requirements¶

Attribute	Scenario	Approach
Privacy	A draft ADR must not be uploaded just to preview PDF	local-first renderer
Security	USER must not publish prompt config	Cognito roles, server-side authorization
Cost	A runaway compile must not unbounded-bill the founder	credits, job limits, replaceable provider
Operability	Environment must be rebuildable	Terraform, GitHub Actions OIDC
Change isolation	AI behavior changes without app deploy	runtime / versioned prompts
Integrity	Missing source facts must not appear as truth	target: fail or warn instead of invent

Failure Modes¶

Risk	Impact	Mitigation
Prompt or model regression	Worse artifacts in production	prompt versions, rollback, INTERNAL publication
Unbounded LLM cost	Bill shock	credits, limits, job timeouts
Webhook spoofing	Fake credit grants	Paddle signature verification
Public S3 origin	Asset or config exposure	private origin + OAC
Long-lived CI keys	Credential leak	GitHub OIDC
Semantic-check theatre	False confidence in output	distinguish deterministic vs probabilistic checks
Local/cloud split confusion	User thinks content stayed local after compile	explicit compile action

Sizing and Cost Notes¶

Primary load drivers¶

local rendering (client CPU; not billed as AWS compute);
transformation job rate and token volume;
admin observability queries;
CloudFront traffic for the SPA;
DynamoDB reads/writes for jobs, credits, and config.

Primary cost drivers¶

LLM provider usage (dominant variable cost);
Lambda / API Gateway;
DynamoDB;
CloudFront and S3;
Cognito MAU;
Paddle fees;
observability storage.

Scaling tiers¶

See Roadmap and Demonstration.

Operations¶

Terraform for AWS;
GitHub Actions for build and deploy;
logs / metrics in the AWS account (exact backends TBD in this pack);
credit / cost protection on jobs;
runtime configuration and admin control plane;
prompt rollback without application redeploy.