
Doculyze: Turn Confusing Documents into Clear Answers — Built on AWS
Doculyze is an agent that reads any document and explains it back to you in plain language — what it says, what matters, and what to watch out for. Upload a lease, a bill, a syllabus, anything — get a summary, flagged risky clauses highlighted on the original page, an explanation read aloud automatically, and a chat panel to ask follow-up questions by voice. Built on a 7-service AWS serverless pipeline.
Doculyze: Turn Confusing Documents into Clear Answers — Built on AWS
The Problem
Everyone has a drawer — physical or digital — full of documents they signed, skimmed, or filed away without really understanding: a rental agreement, an electricity bill, a course syllabus, a job offer letter, a terms-of-service page nobody reads. The language is dense, the formatting is unhelpful, and the parts that actually matter — a deadline, a penalty clause, an auto-renewal — are buried in the same font as everything else.
Most people don't have a lawyer on call for a lease, or the patience to read eleven pages of a syllabus to find the one line about late submissions. That gap — between having a document and understanding it — is what Doculyze closes.
The Solution
Doculyze is an agent that reads any document and explains it back to you in plain language — what it says, what matters, and what to watch out for. Upload a PDF, a photo, or a scanned file and get:
- A plain-language summary of what the document actually says
- Key terms pulled out — dates, numbers, obligations
- Flagged clauses worth double-checking, highlighted at their exact position on the original document
- Concrete next steps — what to actually do about it
- Spoken aloud automatically, and a chat panel — by text or by voice — to ask follow-up questions grounded in that document
- A clean PDF export of the whole explanation
There's no dropdown asking what kind of document you're uploading. The same pipeline reads a one-page bill and a twenty-page lease identically — the agent figures out what it is and adapts, rather than the code assuming ahead of time.
Who It's For
- Renters & tenants — understand lease terms, deposits, and notice periods before signing, or after something feels off
- Students — turn a dense syllabus into a clear list of deadlines and grading rules
- Consumers — make sense of bills, warranties, and terms of service without reading every line
- Employees — get a plain-language read on offer letters and benefits paperwork
- Anyone, honestly — those are just the most common cases; the pipeline doesn't limit itself to a fixed list of document types
Architecture
Browser (React, single-page)
│
│ POST /upload (base64 file)
▼
Amazon API Gateway (HTTP API)
│
▼
AWS Lambda: upload_handler
│ 1. writes file to S3
│ 2. starts a Step Functions execution
▼
Amazon S3 ◀────────────────┐
(raw uploads) │
│
AWS Step Functions — doculyze-explain-workflow
│
├─▶ Lambda: start_extraction ── Amazon Textract StartDocumentAnalysis (async job)
│ │
│ ▼
│ Wait 5s ──────────────┐
│ │ │
│ ▼ │
├─▶ Lambda: check_extraction ── Amazon Textract GetDocumentAnalysis
│ │ IN_PROGRESS ──┘ (loops back to Wait)
│ │ FAILED ──────────▶ save_result (failed)
│ │ SUCCEEDED
│ ▼
├─▶ Lambda: explain_document ── direct HTTPS call to Groq
│
└─▶ Lambda: save_result ── Amazon DynamoDB (write)
Browser polls:
GET /result/{id} → Lambda: get_result → DynamoDB
GET /results → Lambda: get_result → DynamoDB (list)
On the results page:
POST /chat → Lambda: chat → DynamoDB (read) + Groq
GET /document/{id} → Lambda: get_document_url → DynamoDB (read) + presigned S3 URL
Client-side only, no backend call:
Web Speech API — reads the explanation aloud, and powers
voice input in chat, entirely in the browser
AWS services used, and what each one is doing
Service | Role in Doculyze |
|---|---|
Amazon S3 | Stores every uploaded document. Also the source the presigned document-viewer URLs point at. |
Amazon Textract | Reads the document — text, tables, key/value pairs, and the exact on-page position of every line. Called asynchronously ( StartDocumentAnalysis / GetDocumentAnalysis ), not the synchronous API, specifically so a single-page bill and a twenty-page lease go through the identical code path with no special-casing. |
AWS Step Functions | Orchestrates the whole pipeline as a visible, debuggable state machine — extraction, the poll loop, explanation, and saving the result — with per-stage retries instead of retrying an entire monolithic function on any failure. |
AWS Lambda | Every unit of compute in the backend — eight functions total, each doing one job. Nothing runs, and nothing costs anything, when no one is uploading a document. |
Amazon DynamoDB | Stores each analysis result — status, summary, flagged clauses, raw extracted text (for chat), and the document's S3 location (for the viewer) — on-demand billing, no provisioned capacity to manage. |
Amazon API Gateway | A single HTTP API fronting all six externally-callable Lambda functions, with CORS handled at the gateway level. |
AWS X-Ray (via Tracing: Active ) | Every Lambda function traces its execution, so a slow or failing step is traceable end-to-end across the whole pipeline, not just visible in isolated logs. |
That's seven distinct AWS services working together in one pipeline — not one Lambda calling one API. The one deliberate exception is explained below.
Why Groq Instead of Amazon Bedrock
The explanation step originally called Amazon Bedrock, and it worked. It was ultimately swapped for Groq for reasons worth being upfront about, since it's the one place this project steps outside AWS:
- Model access friction. Bedrock requires explicitly requesting and being granted access to each individual foundation model, per AWS account, per region, before a single API call succeeds. On a fresh or restricted account — exactly the kind of account you're often working with mid-hackathon — that approval step can introduce real delay at the worst possible time.
- Regional availability gaps. Not every Bedrock model is available in every AWS region, which can quietly force a redeploy into a different region depending on which model you want.
- Inference speed. Groq's LPU hardware is built specifically for fast token generation. For a live, interactive feature like chat — where a visible delay breaks the conversational feel — that speed difference is noticeable, not theoretical.
- Iteration speed during a hackathon. A free-tier Groq API key works immediately, with none of the account-level approval steps above, which matters when the clock is running.
We also initially tried reaching Groq through the Strands Agents SDK rather than calling it directly, for its agent-framework structure. That introduced its own problems —
strands-agents has a hard dependency on mcp (Model Context Protocol support this app never uses), which in turn requires pywin32 on Windows, breaking sam build on a native Windows machine over a dependency completely unrelated to what we needed Strands for. On top of that, its installed size (~130MB, or ~314MB through the more commonly documented LiteLLM path — over Lambda's 250MB unzipped limit outright) added real cold-start and build-time cost for agentic features — tool use, multi-step reasoning, MCP — this app never exercises.The honest scorecard:
explain_document and chat now call Groq's chat completions API directly over HTTPS with Python's built-in urllib — zero extra dependencies, builds identically on any OS, and the deployment package is back to the same lean size it had with Bedrock. Every other service in the architecture table above is still genuinely AWS. If "Built on AWS" is weighted specifically on the model host, that's the one honest trade-off here — made for reasons of access friction and live-demo latency, not because Bedrock doesn't work.One more thing worth flagging for anyone building on this: Groq recently moved
llama-3.3-70b-versatile and llama-3.1-8b-instant to its Enterprise-only tier. Doculyze defaults to openai/gpt-oss-120b now — Groq's own recommended replacement.Backend Functions
Function | Trigger | Does |
|---|---|---|
upload_handler | POST /upload | Stores the file in S3, starts the Step Functions execution |
start_extraction | Step Functions | Starts an async Textract job ( StartDocumentAnalysis ) |
check_extraction | Step Functions (polled) | Checks job status; once done, pages through all Textract result batches via NextToken and extracts text, key/value pairs, and each line's position on the page |
explain_document | Step Functions | Sends extracted text directly to Groq's chat completions API, parses the structured explanation, and locates each flagged clause's exact quote against the extracted lines to attach a highlight position |
save_result | Step Functions | Writes the final result (or failure) to DynamoDB, including the raw text and S3 location needed by the two functions below |
get_result | GET /result/{id} , GET /results | Serves results to the frontend |
chat | POST /chat | Answers follow-up questions about an already-analyzed document via a direct Groq call seeded with the prior conversation, grounded in the document's stored text |
get_document_url | GET /document/{id} | Returns a short-lived presigned S3 URL for the original file, so the frontend can render it with highlight overlays |
Frontend Features
Beyond upload → explain, the results view includes:
- Document preview with highlights — the original file (image or multi-page PDF, rendered client-side with
pdfjs-dist) shown with each flagged clause highlighted at its actual position on the page. A flag whose exact wording couldn't be matched back to a position is still listed in text — it just won't have a highlight, rather than failing anything.
- Spoken explanation — as soon as an explanation is ready, the browser reads it aloud automatically, with a Listen/Stop control in case autoplay is blocked or you want to replay it.
- Chat, by text or by voice — ask follow-up questions about the document; a microphone button lets you ask by speaking instead of typing (Chrome/Edge only — the button simply doesn't render in browsers without voice-input support), and each answer has its own "read aloud" toggle. Answers are grounded only in that document's extracted text.
- Download as PDF — a clean, text-based PDF of the explanation (not a screenshot), generated client-side with
jspdf.
Voice features use the browser's built-in Web Speech API — no backend, no new AWS service, no extra bundle weight, and every call is feature-detected so unsupported browsers just don't show the button rather than showing a broken one.
What's Next
- AWS Secrets Manager for the Groq API key instead of a plain Lambda environment variable
- Amazon Cognito for user accounts, so each person's document history is private and persistent
- Amazon Polly as a higher-quality alternative to the browser's built-in Web Speech API for narration
- Amazon Transcribe for voice input that works in every browser, not just Chromium-based ones
- Multi-language support — explain a document in a language other than the one it's written in
- Batch upload — analyze several documents in one pass
- CloudFront + WAF in front of the API for production-grade caching and abuse protection
- CI/CD via GitHub Actions or AWS CodePipeline
Closing Thought
The most interesting engineering here wasn't any single service — it was the discipline of not special-casing anything. No document-type dropdown. No hardcoded categories. One pipeline that reads a bill and a lease identically, and lets the model — not the code — decide what it's looking at. That constraint, more than any individual AWS service, is what made this feel like a real agent rather than a form with extra steps.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article