DDLC-ADM
Documentation Development
Lifecycle Architecture
Phases A through F

"Why not use a hosted backend? Render free tier is free, gives you proper server-side processing, and doesn't expose an API key in the browser."

Render free tier FastAPI backend with server-side Groq calls. Clean separation of concerns. API key never in the browser. Standard web architecture.

Render free tier spins down after 15 minutes of inactivity — the first pipeline run after idle takes 30+ seconds just to wake the dyno, destroying the sub-15-minute target. More critically: a backend receives Maya's document content. For an enterprise writer, this is a data governance question. Client-side means document content goes only to Groq (writer's own key), never to a third-party infrastructure layer we operate. The zero-server guarantee is a real enterprise privacy argument, not a cost optimisation.

API key visible in localStorage (mitigated by scoping the key to Groq only, not a master credential). No server-side rate limiting. No server-side logging for debugging. These are acceptable for a portfolio MVP where the privacy guarantee is worth more than the operational convenience.

"Why Groq and not OpenAI or Anthropic? Those models produce better technical writing quality and have more predictable outputs."

OpenAI GPT-4o mini (cheap) or Anthropic Claude Haiku (excellent technical writing). Both produce higher-quality output on complex technical prose than Llama 3.1 70B.

C-01 (zero infrastructure cost) is a binding constraint. GPT-4o mini and Claude Haiku both cost money at any meaningful usage volume. Groq's free tier delivers Llama 3.1 70B at 300+ tokens/second — fast enough for a 5-agent pipeline to complete in under 15 minutes. Speed compensates for the modest quality delta. The abstraction layer is designed to swap to Together AI (also free tier) if Groq changes its pricing. Quality on technical documentation is adequate; it is not the differentiator — the pipeline architecture is.

Llama 3.1 70B produces slightly less polished technical prose than GPT-4o or Claude. The Compliance Agent catches style violations regardless of model quality. The writer reviews and edits before publishing. Model quality is the least important variable in a pipeline with a mandatory human gate.

"Why 5 separate API calls? That's 5× the latency, 5× the cost, and you could do this in one large system prompt with chain-of-thought."

One large LLM call with a structured system prompt: "You are a technical writing pipeline. Do intake, research, drafting, compliance, and review prep in one pass. Output JSON with all sections."

Single-agent collapse destroys XAI. If the entire pipeline is one call, what does the reasoning card say? "I did everything"? The value of multi-agent is that each stage has a discrete, inspectable output with a named confidence score. The Research Agent's uncertainty about an unknown proper noun is a specific, actionable piece of information the writer can act on. Collapsed into one call, that uncertainty is invisible. Additionally: AR-06 (single responsibility) is a binding principle. Single-agent compliance is not a trade-off — it's a principle violation.

~4–5 additional API calls per session at Groq speeds (~1–2s per call) adds 5–8 seconds of total latency. At 300+ tok/s, this is negligible. The pipeline monitor makes the latency feel like progress rather than waiting — the writer watches each stage complete in real time.

"Why not RAG the full Google Style Guide? A proper vector search over the full guide would catch far more violations than 80 curated rules."

Embed the full Google Developer Style Guide into a client-side vector store (transformers.js + HNSW), run semantic search at compliance time, return the top-N matching rules for every sentence.

RAG over the style guide introduces hallucinated citation risk — the LLM finds semantically similar passages and may cite them inaccurately. The entire value of the Compliance Agent is that every violation has a named, citable rule the writer can look up. A RAG system that returns approximate matches with uncertain provenance is worse than no compliance check — it trains the writer to distrust the output. The 80-rule JSON is deterministic: rule ID 047 = "avoid Latin abbreviations". That is binary. It either fires or it doesn't. Additionally, client-side vector search adds 200–400KB of model weight and 1–2s of load time for marginal coverage gain. Not worth it.

80 curated rules cover the high-impact, verifiable subset of the style guide. Edge cases and stylistic judgment calls are left to Maya. The compliance check is not meant to be exhaustive — it is meant to be accurate and citable. Coverage over correctness is the wrong trade-off for a tool whose XAI principle depends on every output being trustworthy.

"Why implement a LangGraph-pattern manually in JS? Just use an autonomous agent loop — give the LLM a list of tools and let it decide the sequence."

AutoGPT-style agentic loop: give the LLM a set of tool descriptions, let it decide which tool to call next, iterate until it decides the task is done. Simpler implementation, more "agentic".

Non-deterministic agent loops violate P-02 (human gate as non-bypassable) and AR-02. If the LLM decides the sequence, it might skip the Compliance Agent when it "decides" the draft is already clean. The pipeline must be deterministic — every session runs every stage in the defined order. The human gate fires after Review Prep, always, not when the LLM thinks the document is ready. Additionally, autonomous loops are difficult to test and impossible to explain — which violates P-01 (explainability engineered in). A LangGraph-pattern graph with defined nodes and edges is inspectable, testable, and the XAI layer knows exactly which node produced which output.

Less "agentic" in the AutoGPT sense — the pipeline doesn't self-direct. More robust, more explainable, more compliant with the architecture principles. For a documentation tool where compliance and human oversight are first-class concerns, deterministic pipelines are strictly better than autonomous loops.

"Why is the Ambiguity Detector a separate agent? Just add 'check for ambiguous language' to the Draft Agent's system prompt. That's one less API call."

Add an ambiguity_check field to the Draft Agent's output schema. The same LLM call that produces the draft also flags ambiguous terms. One call, two outputs.

The Draft Agent and the Ambiguity Detector have structurally opposed goals. The Draft Agent's objective is to produce fluent, complete prose — it is optimised for coverage and coherence. The Ambiguity Detector's objective is to find holes, missing definitions, and vague language — it is optimised for critique. Asking one model to be both author and critic in a single call is a known failure mode: the LLM rationalises the content it just produced rather than genuinely critiquing it. A separate agent call, with a system prompt scoped exclusively to ambiguity detection and given the draft as an external artefact, produces significantly better detection rates than self-critique. AR-06 (single responsibility) also applies: the Ambiguity Detector's output contract is an AmbiguityReport, not a DraftDocument with embedded notes.

One additional API call per P2 session (~2 seconds at Groq speeds). This pushes the P2 pipeline to a 20-minute target vs the P1 15-minute target. The quality gain from genuine self-critique separation is worth the latency. The 5-minute differential is disclosed clearly in the UI.