Hacktoberfest 2026 I - Submission for a friend

A developer is building "Paperwork Translator," a mobile-first PWA that lets non-technical Spanish speakers photograph documents such as CFE electricity bills, SAT notices, or court summonses and receive plain-language explanations, deadline and amount extraction, step-by-step guidance, fraud warnings, and downloadable .ics calendar reminders. The project, an entry in the DEV Hacktoberfest Weekend Challenge 2026, runs entirely on open-source AI components with no closed-model APIs at runtime, and is developed in a FastAPI/SQLModel monorepo under a GitFlow workflow with non-stacked pull requests.

now help me to accomplish this huge feature: I'm entering the DEV Hacktoberfest Weekend Challenge 2026 "Build for a Friend" . The project MUST comply with these rules: - The repo was created within the challenge window, which closes Monday, October 5, 00:59 Mexico City time. I want a working MVP by Sunday at 15:00 so I have time for the write-up and to hand it over. - Open-source AI must be the core of the product: at runtime, NO closed-model APIs are used no Claude, OpenAI, or Gemini . You're helping me build it, but the product runs entirely on open components. - Any commits after the deadline must be documented in the README. All architecture decisions below are already made. Build the whole project end to end, following the build order, without waiting for confirmation between steps unless a step explicitly says to stop. Time is the main constraint: always choose the simplest solution that works. Git workflow: GitFlow with non-stacked PRs ESSENTIAL, never skip Branches: - main: production only. Changes arrive only through release/ or hotfix/ PRs. - develop: integration branch. Changes arrive only through feature/ PRs. - feature/<short-name : one per build step, always created from the latest develop. - release/<version : created from develop when the MVP is ready; PR into main, then merged back into develop. - hotfix/<short-name : from main, only for urgent production fixes; PR into main and merged back into develop. Rules: - Never commit directly to main or develop. - One feature branch per build step, one PR per feature branch, base branch = develop. - NO stacked PRs: never create a branch from another feature branch, and never open a PR whose base is anything other than develop or main for release/hotfix . - Sequence for every step: 1. git checkout develop && git pull 2. git checkout -b feature/<name 3. Work with small Conventional Commits. 4. Run lint + typecheck + tests for the parts touched; all must pass. 5. Push and open the PR with gh pr create --base develop. 6. Merge it with gh pr merge merge commit, delete the branch . 7. Only then start the next step from the updated develop. - PR description: what changed, why, how it was tested, and whether DECISIONS.md was updated. - PR title follows Conventional Commits. The product: "Paperwork Translator" A mobile-first web app for my mom. She takes a photo of a document an electricity bill from CFE, a bank letter, a notice from the SAT tax authority, a court summons, etc. or records a voice question about it. The app replies in plain, simple Spanish, with no jargon, covering: 1. What the document is and who sent it. 2. Whether there's a deadline and how much she owes if applicable . 3. What she needs to do, in short steps. 4. A clear warning if it looks like fraud or phishing requests for personal data, suspicious urgency, strange links . If there's a deadline, she can tap "Agregar a mi calendario" to download an .ics reminder set a few days before the due date. A simple history screen lists her past documents and upcoming deadlines. Behavior rules for the AI responses: - ALL user-facing text is in Spanish Mexican Spanish, warm and simple . - If the photo is unreadable or the model isn't confident, say so and ask for another photo. Never make up amounts or dates. - Explain only; no legal or financial advice. For serious cases summons, lawsuits, large debts recommend talking to her son or a professional. - Never ask for passwords, PINs, card numbers, or ID numbers. UX for an older, non-technical user: - Two big primary buttons on the home screen: "Tomar foto" and "Preguntar con voz". - Large text, high contrast, minimal steps, no jargon, clear loading state. - Installable as a PWA add to home screen . Architecture Monorepo: /api FastAPI Python 3.12+, uv, Pydantic, SQLModel, SQLite, pytest, ruff . - POST /documents/analyze: receives an image, calls Gemma 4 via Ollama with a strict JSON schema, returns structured data: document type, issuer, deadline, amount, required actions, fraud flag + reason, confidence, and a plain-Spanish explanation. Validate model output with Pydantic; on invalid output, retry once, then return a low-confidence result instead of guessing. - POST /questions/voice: receives audio, answers the question optionally about a previously analyzed document . - GET /documents: history. GET /documents/{id}/reminder.ics: calendar reminder. /web Nuxt latest stable, TypeScript strict , mobile-first PWA, UI in Spanish. Camera capture and audio recording via standard browser APIs. Minimal access protection: a single family access code stored in a cookie. /samples Anonymized test documents already provided . /docs DECISIONS.md. Root: README.md, CLAUDE.md, .claude/rules/, docker-compose.yml Ollama + api + web for local dev , render.yaml Render Blueprint , .env.example, .gitignore. Model: Gemma 4 Apache 2.0 via Ollama, running locally during development. Audio: if Ollama supports Gemma 4 audio input, use it; otherwise transcribe with faster-whisper open source and send the text to Gemma 4. Privacy this is the project's core argument - Images and audio are processed in memory and discarded; never stored. - Only the extracted structured data is persisted. - No logging of document contents or personal data. - Secrets in .env, never in the repo. - Tests and demos use only the anonymized documents in /samples. Build order each step = one feature branch + one PR into develop 1. Git setup: verify the GitHub remote and that gh is authenticated if not, STOP and tell me . Ensure main exists, create develop from main, and push it. 2. feature/scaffold: /api with uv, /web with Nuxt, docker-compose.yml, .env.example, .gitignore, docs/DECISIONS.md. 3. feature/claude-memory: Claude Code project memory, following current Claude Code practices. Keep every file short: only what you can't infer from the code and what differs from standard conventions. a. CLAUDE.md at the repo root committed , under ~60 lines: - One-paragraph project overview and the monorepo layout. - Exact commands: install, run api, run web, run Ollama, test, lint, typecheck. - The GitFlow and non-stacked PR rules above, condensed. - Workflow: run lint + tests for the part you touched before each commit; Conventional Commits; update docs/DECISIONS.md when a technical decision is made or changed; check official docs instead of guessing Ollama/Nuxt/Render APIs. - Non-negotiables: no closed-model APIs at runtime; images and audio never written to disk or logs; never log document contents or personal data; all user-facing text in Spanish, everything else in English. - A "Gotchas" section, updated as we discover them. b. .claude/rules/api.md with paths frontmatter scoped to api/ : - Config only via pydantic-settings and .env. - Every model output validated with Pydantic; retry once, then low confidence. - Ollama calls async with explicit timeouts; a model failure never crashes a request. - Prompts live in api/prompts/, versioned, never inline. - Unit tests mock the model; one integration test hits the real model using /samples. - Validate upload type and size before processing. c. .claude/rules/web.md with paths frontmatter scoped to web/ : - API base URL only via runtimeConfig; no secrets in client code. - Composables handle API calls; components stay presentational. - All UI strings centralized in one file, in Spanish. - Designed for an older, non-technical user: large tap targets, high contrast, always-visible loading and error states. d. CLAUDE.local.md in .gitignore only for machine-specific settings: local Ollama URL, the Gemma 4 tag pulled, and the local access code for testing. 4. feature/model-spike: check the exact Gemma 4 tag in the Ollama docs, pull it, and write a script in /api that sends the images in /samples with the extraction schema and prints the results. If the reading quality in Spanish is poor wrong amounts or dates, unreadable text , STOP before opening the PR and show me the results with options. Otherwise, summarize the results in DECISIONS.md and continue. 5. feature/api-analyze: /documents/analyze with tests. 6. feature/api-history-reminder: history endpoint and .ics reminder, with tests. 7. feature/web-photo-flow: home with the two buttons, photo flow, result screen, connected to the API. Verify the photo flow works end to end locally. 8. feature/web-history-pwa: history screen and PWA setup. 9. feature/voice-questions: check the Ollama docs for Gemma 4 audio support first. 10. feature/deploy-render: render.yaml for /api and /web, deploying from main. Check whether Render offers GPUs for inference. If not, STOP and propose the alternatives a smaller Gemma 4 variant, a DigitalOcean GPU Droplet, or inference on my own machine exposed securely with pros and cons, and wait for my choice. 11. feature/readme: README in English: what it is, who it's for, architecture diagram, how to run it, the branching model, and a "Why open source matters here" section privacy, zero cost per request, control over the model . 12. release/1.0.0: from develop, PR into main, merge, tag v1.0.0, then merge main back into develop. Priority if time runs short: photo flow end to end history .ics reminder voice. Even when cutting scope, never skip the GitFlow sequence. General rules - Code, comments, commits, PRs, and README in English. All user-facing text in Spanish. - Don't invent Ollama, Nuxt, or Render APIs or flags: when unsure, check the official docs before writing code, and tell me if something isn't documented. - Ask before installing anything globally or touching anything outside the repo. - Keep docs/DECISIONS.md logging each technical decision and why; I'll use it for the post. - Whenever I correct you on something that should apply to future sessions, propose adding it to CLAUDE.md or the right rules file instead of only fixing the code.