DocuFlow AI is designed for small and medium businesses that need to process invoices and receipts with less manual work. The platform allows authenticated users to upload PDF, JPG, or PNG documents, then uses AWS managed services to extract financial fields, normalize the result, store metadata, and show the processing status in a simple web interface.
The solution uses a serverless, event-driven architecture deployed with AWS SAM in ap-southeast-1 (Singapore). Users access the frontend through Amazon CloudFront and AWS Amplify, sign in with Amazon Cognito, and upload documents through presigned URLs. Amazon S3 stores the original files, EventBridge and SQS decouple ingestion from processing, Step Functions orchestrates the workflow, Amazon Textract extracts invoice and receipt data, an AI Proxy Lambda calls an External AI API to normalize the extracted result, a Confidence + Status Lambda determines the final status, and DynamoDB stores document status and metadata.
The workshop is scoped for a five-person team. Each member owns one module: frontend/auth/upload, ingestion/workflow, AI extraction and validation, data/result dashboard, and observability/security/IaC.
Many businesses still process invoices and receipts through email, shared folders, spreadsheets, or manual data entry. This creates several issues:
DocuFlow AI centralizes document upload and processing on AWS. The frontend provides login, upload, status tracking, result viewing, and manual correction. The backend uses presigned URLs for secure upload to S3, then processes documents asynchronously with EventBridge, SQS, Lambda, and Step Functions.
Amazon Textract extracts invoice and receipt fields. An AI Proxy Lambda sends only the minimized Textract output to the External AI API, maps inconsistent field names into a consistent schema, classifies the document as invoice or receipt, explains missing fields, and returns structured JSON. Lambda validates the schema, confidence score, and business rules before saving the result to DynamoDB and S3 processed storage. The frontend never calls the external AI API directly, and raw PDF or image files are not sent to the external AI provider unless the team explicitly approves that behavior.
DocuFlow AI reduces manual data entry and gives teams a repeatable process for handling financial documents. The system creates a searchable metadata store, provides status visibility, and supports a review loop for low-confidence documents. Because the MVP is serverless, the platform can stay low-cost for a workshop workload and scale with document volume when needed.
The estimated AWS cost for the workshop workload is about $3.50-$8.00 per month, or $42-$96 for 12 months in ap-southeast-1 (Singapore), depending on Textract pages, External AI API usage, CloudWatch/X-Ray volume, log retention, and alert testing. The project also provides reusable learning value for AWS serverless architecture, AI document processing, asynchronous workflows, secure secret handling, observability, governance, and cleanup.
DocuFlow AI uses a serverless AWS architecture for secure upload, asynchronous processing, AI-assisted extraction, result storage, and operational monitoring. The high-level architecture is shown below:

The diagram reflects the approved architecture scope: CloudFront, Amplify, Cognito, API Gateway, Lambda, S3 Raw/Processed buckets, EventBridge, SQS with DLQ, Step Functions Standard Workflow, Textract, AI Proxy Lambda, External AI API, DynamoDB, CloudWatch, X-Ray, SNS/SES, IAM, KMS, Secrets Manager, CloudTrail, Budgets, and SAM.
The services below are grouped by architectural layer. Each row maps directly to the Budget Estimation in section 6.
Identity & Security
aws/s3, aws/dynamodb, aws/sqs) for encryption at rest; no customer-managed keys to keep cost at $0.Frontend Delivery
API & Compute
POST /documents/upload-url, GET /documents, and GET /documents/{id}, all protected by the Cognito authorizer.generateUploadUrl, jobStarter, validateDocument, textractExtraction, aiProxyNormalization, confidenceStatus, and statusApi. Notification logic can be implemented as a dedicated Lambda or as a workflow task depending on the final SAM template.Storage
docuflow-raw (Block Public Access, SSE-KMS, 60-day lifecycle expiration) and docuflow-processed (versioned, transition to STANDARD-IA after 30 days).Documents keyed by documentId, with a GSI on userId+status for the user dashboard; stores metadata, status, confidence score, normalized fields, AI provider/model metadata, S3 paths, and error codes.Eventing & Workflow
Object Created events and routes them to SQS.AnalyzeExpense, invokes the AI Proxy Lambda, runs confidence/status logic, saves metadata to DynamoDB, saves processed JSON to S3, and routes low-confidence or failed documents to REVIEW_REQUIRED or FAILED.AI Services
AnalyzeExpense: Purpose-built API for invoices and receipts; returns SUMMARY_FIELDS and LINE_ITEM_FIELDS consumed by the External AI normalization step.Observability & Notification
Operations & Cost
The happy path for a single invoice or receipt traverses the system as follows:
generateUploadUrl Lambda creates a documentId, writes an initial DynamoDB record, and returns a short-lived S3 presigned URL.UPLOADED to QUEUED.PROCESSING.AnalyzeExpense to extract invoice/receipt fields.EXTRACTED, REVIEW_REQUIRED, or FAILED.result.json is saved to the S3 Processed Bucket.CORRECTED and final results to APPROVED.Failure paths are handled by Step Functions Catch branches and SQS retry/DLQ rather than ad-hoc Lambda try/catch. When any state catches an error, the workflow transitions to MarkFailed (or MarkReviewRequired for low-confidence or schema issues) and the DynamoDB status is updated accordingly. Ingestion failures occurring before Step Functions starts are absorbed by SQS retry and end up in the DLQ.
The project runs in four short phases. Section 5 breaks each phase into specific weeks.
end-user, reviewer, admin — wired into API Gateway as a Cognito authorizer.AnalyzeExpense, AI Proxy Lambda, Confidence + Status Lambda, JSON schema validation, Retry/Catch on each state, and explicit status transitions.UPLOADED → QUEUED → PROCESSING → EXTRACTED / REVIEW_REQUIRED / FAILED → CORRECTED → APPROVED.Documents with PK documentId and a GSI on userId+status. Item attributes: documentId, userId, fileName, documentType, status, normalized fields, confidenceScore, reviewReasons, aiProvider, normalizationMethod, s3RawPath, s3ProcessedPath, errorCode, createdAt, and updatedAt.All modules share one JSON contract so frontend, workflow, storage, API response, and analytics stay consistent:
{
"documentId": "doc-001",
"userId": "user-123",
"fileName": "invoice-001.pdf",
"documentType": "INVOICE",
"status": "EXTRACTED",
"vendorName": "ABC Company",
"invoiceDate": "2026-06-01",
"currency": "VND",
"totalAmount": 2500000,
"taxAmount": 250000,
"confidenceScore": 0.91,
"reviewReasons": [],
"aiProvider": "external-ai-api",
"normalizationMethod": "TEXTRACT_PLUS_AI_PROXY_EXTERNAL_API",
"s3RawPath": "s3://docuflow-dev-raw-bucket/raw/user-123/doc-001/original.pdf",
"s3ProcessedPath": "s3://docuflow-dev-processed-bucket/processed/user-123/doc-001/result.json",
"createdAt": "2026-06-08T10:00:00Z",
"updatedAt": "2026-06-08T10:01:00Z"
}
The External AI API receives a minimized payload only:
{
"documentId": "doc-001",
"fileName": "invoice-001.pdf",
"textractSummaryFields": [
{
"type": "VENDOR_NAME",
"text": "ABC Company",
"confidence": 0.96
},
{
"type": "TOTAL",
"text": "2,500,000 VND",
"confidence": 0.93
}
],
"textractLineItems": [],
"rawTextPreview": "Invoice ABC Company total 2,500,000 VND..."
}
The payload must not include raw PDF files, raw images, API keys, AWS credentials, full documents when not necessary, or unrelated sensitive information. The AI Proxy Lambda validates that the response is valid JSON, documentType is INVOICE, RECEIPT, or UNKNOWN, totalAmount is numeric, invoiceDate is ISO-8601 when available, confidenceScore is between 0 and 1, and low-confidence or missing required fields are represented in reviewReasons.
The stack below complements the AWS services in section 3. It is the concrete code-level toolset the team uses to build, test, deploy, and document the platform.
Frontend
| Layer | Choice | Notes |
|---|---|---|
| Language | TypeScript 5 | Shared types with backend via a workspace package |
| Framework | React 18 | Single-page app delivered through CloudFront and deployed by Amplify |
| Build tool | Vite | Fast HMR, zero-config TypeScript |
| Auth | amazon-cognito-identity-js | Official lightweight Cognito SDK; talks to the User Pool from section 3 |
| API client | axios + @tanstack/react-query | Axios interceptor injects the Cognito JWT; TanStack Query caches server state |
| UI | shadcn/ui + Tailwind CSS | Component primitives, no vendor lock |
| Forms | React Hook Form + Zod | Zod schemas reused server-side |
| Routing | React Router v6 | |
| Testing | Vitest (unit) | E2E is out of scope for the workshop |
Backend Lambda
| Layer | Choice | Notes |
|---|---|---|
| Runtime | Node.js 20.x at 256 MB | As declared in sections 3 and 4 |
| Language | TypeScript 5 | Compiled with esbuild via SAM |
| AWS SDK | AWS SDK v3 modular packages | client-s3, s3-request-presigner, client-dynamodb, lib-dynamodb, client-textract, client-secrets-manager, client-sns, client-sfn |
| External API client | fetch / undici with timeout and retry limits | Calls the External AI API only from AI Proxy Lambda |
| Validation | Ajv (JSON Schema) + Zod | Ajv enforces the AI Proxy JSON contract; Zod validates HTTP payloads |
| Observability | AWS Lambda Powertools for TypeScript + X-Ray SDK | Structured logs, custom metrics, tracing |
| Testing | Vitest + aws-sdk-client-mock |
Infrastructure & DevOps
| Concern | Choice | Notes |
|---|---|---|
| IaC | AWS SAM | Uses the CloudFormation transform; teardown via sam delete or aws cloudformation delete-stack per the section 7 contingency |
| Local Lambda | AWS SAM CLI (sam local invoke, sam local start-api) | |
| External AI API | Configured provider/model through environment variables | API key stored in Secrets Manager; raw files are not sent by default |
| Monorepo | pnpm workspaces | |
| Linting | ESLint + Prettier | One shared config across apps/*, services/*, packages/* |
| Secrets scan | gitleaks pre-commit hook | Blocks accidental key commits |
| CI/CD | Amplify Hosting for frontend; GitHub Actions with OIDC → IAM role for backend | Jobs: lint-test on PR, deploy-dev on main, deploy-prod on a v* tag |
| Documentation | Hugo + Learn theme (this repo) | Bilingual EN/VI, diagrams in draw.io |
Repository Layout
docuflow-ai/
├── frontend/
│ └── src/ # React + Vite frontend deployed by Amplify
├── backend/
│ ├── functions/
│ │ ├── upload-url/
│ │ ├── job-starter/
│ │ ├── textract-extraction/
│ │ ├── ai-proxy-normalization/
│ │ ├── confidence-status/
│ │ ├── status-api/
│ │ └── notification/
│ └── shared/
│ ├── schema/ # JSON schema and Zod DTOs
│ └── utils/
├── infrastructure/
│ ├── template.yaml # SAM root template
│ └── parameters/{dev,demo}.json
├── docs/
│ ├── architecture/
│ ├── test-evidence/
│ └── demo-script.md
└── samples/
├── invoices/
└── receipts/
The Lambda function folders mirror the responsibilities declared in section 3, and the shared schema package enforces the same data contract across upload, normalization, storage, API response, and analytics modules.
| Member | Role | Main responsibility |
|---|---|---|
| Hoàng Trọng Trà | Leader / Integration Owner | Ingestion, EventBridge, SQS, Job Starter Lambda, Step Functions, integration flow |
| Vũ Duy Tài | AI Owner | Textract, AI Proxy Lambda, External AI API normalization, confidence/status logic |
| Nguyễn Hữu Tịnh | Frontend/Auth Owner | CloudFront, Amplify, Cognito, API Gateway integration, upload/result/review UI |
| Lâm Quang Lộc | Data Owner | DynamoDB, S3 processed JSON, metadata schema, document result management |
| Phạm Tùng Dương | Ops/Security/IaC Owner | IAM, KMS, Secrets Manager, CloudTrail, Budgets, SAM, CloudWatch, X-Ray, SNS/SES |
The budget targets a workshop-scale workload that a five-person team can run end-to-end while staying close to the AWS Free Tier. The official estimate can be created and updated with the AWS Pricing Calculator.
The estimate uses the following baseline so each cost line is reproducible:
ap-southeast-1 (Singapore — closest AWS region to Vietnam, lowest latency for local end users; pricing is moderately higher than us-east-1 for CloudWatch, DynamoDB, API Gateway, and Step Functions, but still well within a workshop budget).| Service | Usage assumption | Monthly cost (USD) |
|---|---|---|
Amazon Textract AnalyzeExpense | 200 pages | $2.00 |
| External AI API | 100 normalization requests, minimized payload | $0.00 – $2.00 provider-dependent |
| AWS Secrets Manager | 1 external API secret | $0.40 |
| AWS Lambda | ~1,200 invocations, 256 MB, ~500 ms | $0.00 – $0.10 |
| Amazon API Gateway (REST) | ~5,000 calls | $0.02 – $0.03 |
| Amazon S3 | 1.5 GB Standard + small request volume | $0.03 – $0.10 |
| Amazon DynamoDB (on-demand) | 1,000 writes + 5,000 reads, < 1 GB storage | $0.05 – $0.30 |
| Amazon EventBridge + Amazon SQS | ~100 events, low queue volume | $0.00 – $0.10 |
| AWS Step Functions Standard | 100 executions × ~9 states | $0.00 – $0.10 |
| Amazon CloudWatch + AWS X-Ray | ~500 MB logs, 7-day retention, traces, ~5 alarms | $0.60 – $1.40 |
| Amazon SNS/SES | ~100 alerts | $0.00 – $0.10 |
| Amazon Cognito | 5–10 MAU (free tier covers 50k) | $0.00 |
| Amazon CloudFront + AWS Amplify Hosting | static React build, low demo traffic, occasional builds | $0.00 – $1.00 |
| AWS CloudTrail + AWS Budgets | management events and spending alerts | $0.00 |
| Total | $3.50 – $8.00 |
Annualized: about $36 – $84 for 12 months. Numbers vary with region, Textract pages, External AI API provider pricing, retry volume, token/payload size, and CloudWatch retention. AWS SAM/CloudFormation (deployment) and AWS Budgets (cost alerts) are also used and stay at $0.00 within free usage limits.
Free Tier coverage depends on the account creation date and selected account plan. Accounts created before July 15, 2025 can still follow the legacy 12-month Free Tier model, while newer accounts may use the current AWS Free Tier plan and credits. Before running the workshop, the team will verify the actual account’s Free Tier status in AWS Billing and keep AWS Budgets alerts at $5 and $10.
For this workload, several services may still be free or near-free at workshop volume, such as Lambda, DynamoDB, SNS, Cognito, CloudFront, and Amplify static hosting. API Gateway, S3 storage, CloudWatch logs/alarms, X-Ray traces, Step Functions, and Amplify build minutes/data transfer must be checked against the active account’s Free Tier and pricing page rather than assumed to be free.
Textract and the External AI API are not covered by AWS Free Tier assumptions in this proposal, so the team must validate both charges directly and keep the monthly workshop budget at or below $10.
If the workload grows 10× to 1,000 documents and 2,000 pages per month, Textract scales linearly to roughly $20/month and the External AI API scales according to provider pricing, retry count, and payload size. The other services stay near current levels, putting the AWS-side platform around $25 – $40/month before provider-specific AI charges.
aws cloudformation delete-stack (or sam delete) on the backend workshop stack, then deletes the Amplify app/branches from the Amplify console or CLI. Together this removes the Cognito User Pool, S3 buckets, DynamoDB table, Step Functions state machine, API Gateway, Lambda functions, EventBridge rules, SQS queues, SNS topic, IAM roles, CloudWatch log groups, and frontend hosting resources.Severity is impact × probability on a 1–3 scale (max 9). Owner refers to the workshop module accountable for the mitigation.
| ID | Risk | Impact | Probability | Severity | Owner |
|---|---|---|---|---|---|
| R-01 | Scope creep beyond invoice/receipt MVP | High (3) | Medium (2) | 6 | Tech lead |
| R-02 | Low Textract accuracy on poor scans | High (3) | Medium (2) | 6 | AI module |
| R-03 | External AI API returns malformed JSON / wrong schema | Medium (2) | Medium (2) | 4 | AI module |
| R-04 | Asynchronous workflow failure (Step Functions / SQS) | High (3) | Low (1) | 3 | Workflow module |
| R-05 | Cost overrun beyond $10/month budget | Medium (2) | Low (1) | 2 | IaC/Ops module |
| R-06 | IAM misconfiguration exposes data | High (3) | Low (1) | 3 | Security module |
| R-07 | External AI API timeout, rate limit, or outage | Medium (2) | Medium (2) | 4 | AI module |
| R-08 | Presigned URL leaked from frontend or logs | High (3) | Low (1) | 3 | Frontend / Security |
| R-09 | Document edge cases (low-DPI scan, encrypted, oversized) | Medium (2) | Medium (2) | 4 | AI module |
| R-10 | Sensitive document data sent unnecessarily to external provider | High (3) | Low (1) | 3 | Security / AI module |
| R-11 | External AI API key leaked or missing | High (3) | Low (1) | 3 | Security / IaC module |
REVIEW_REQUIRED for the human review path.REVIEW_REQUIRED if the structure is still invalid.REVIEW_REQUIRED or FAILED instead of blocking the whole workflow.quarantine/ S3 prefix for manual triage.delete-stack script if needed.REVIEW_REQUIRED, show the Step Functions execution history, and use prepared normalized JSON only for the demo UI if the provider remains unavailable.DocuFlow AI replaces manual invoice and receipt entry with a serverless document-processing workflow. It provides secure upload, automated Textract extraction, External AI API normalization through AI Proxy Lambda, schema validation, metadata storage, status tracking, notifications, operational logs, audit visibility, and cost governance.
The workshop is considered complete when each of the following has evidence:
vendorName, invoiceDate, totalAmount, taxAmount, and currency; line-item extraction is treated as bonus evidence because it varies more across document formats.UPLOADED, QUEUED, PROCESSING, EXTRACTED, REVIEW_REQUIRED, FAILED, CORRECTED, and APPROVED.5-Workshop.The project creates a reusable foundation for financial document processing on AWS. Future teams can extend the same pattern to more document types, stronger validation rules, richer reporting, and deeper finance-system integration. For FCAJ, the workshop demonstrates practical use of AWS serverless services, AI-assisted document processing, external API security, audit visibility, cost control, observability, and cleanup in one coherent solution.