DocCompile - architecture review¶

This page assembles sections relevant to architecture review: goals, requirements, and constraints; system model; architecture and integrations; security, quality, and operations; and decisions, trade-offs, and risks.

Contents¶

Summary
Goals, Requirements, and Constraints
System Model
Architecture and Integrations
Security, Quality, and Operations
Decisions, Trade-offs, and Risks

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.

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.

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.

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