Hacktoberfest 2026 I - Submission for a friend

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.

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.

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 state.

• Installable as a PWA (add to home screen). 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.

• 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.

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.

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 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.

• 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.