CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

AGENTS.md contains the canonical command list, platform behavior notes, and deployment/secrets rules. Read it too — this file focuses on the cross-file architecture that AGENTS.md does not spell out.

Commands

Backend (run from repo root, not backend/): uvicorn backend.app.main:app --reload. Imports are absolute from the backend. package, so the working directory must be the repo root.
Frontend: cd frontend && npm run dev (dev), npm run build, npm run lint.
Syntax check: python -m compileall backend (there is no test suite in the repo).
Windows one-click: abrir_estacion.bat → scripts/start-platform.ps1 picks free ports, starts both servers, opens the browser; cerrar_estacion.bat stops only this project.
Container/prod: docker compose up --build, or Nixpacks/Dockerfile.coolify → both run scripts/start-coolify.sh.

Architecture

A two-process app for turning class materials (PDF/DOCX/text/audio/video) into LLM-ready Markdown, organized as Materia → Semana → documentos.

Request → background-job flow

backend/app/main.py is the entire HTTP API (flat FastAPI app, no routers). Every endpoint is a thin try/except that delegates to KnowledgeManager and maps ValueError → 404/400, DuplicateSourceError → 409.
File upload saves the raw file, creates a source row + a job row, then schedules process_job via FastAPI BackgroundTasks (in-process — no external queue/worker). Job status transitions: queued → processing → completed|failed.
process_job calls IngestionService.process_source, which picks a processor by source_type, runs it, wraps the result in Markdown frontmatter, and persists a document.

Key components

KnowledgeManager (managers/knowledge_manager.py) — the single source of truth. Owns both the SQLite schema (subjects, weeks, sources, documents, jobs) and the on-disk layout under data/subjects/<slug>/week-NN/{raw,processed,exports}/. Filesystem and DB are kept in sync here; processors and endpoints must go through it, never write final Markdown or touch the DB directly. Schema migrations are done idempotently in _init_db via _ensure_columns (add-column-if-missing) — there is no migration framework.
IngestionService (services/ingestion_service.py) — maps source_type → processor and assembles frontmatter metadata.
Processors (services/processors/) — each returns a ProcessedContent(title, body, processor) dataclass (base.py). text, docx (python-docx), pdf (PyMuPDF text, or Mistral OCR when use_ocr=true), audio (Deepgram), video (ffmpeg → audio → Deepgram). PDFs accept page_ranges like 1-5,8,10-12.
Providers (services/providers/) — thin HTTP clients for Mistral OCR and Deepgram, keyed off MISTRAL_API_KEY / DEEPGRAM_API_KEY.
markdown_builder.build_markdown — the only place that emits the YAML frontmatter block prepended to every processed document.

Important invariants

One document per source. create_document deletes any prior document/jobs for that source before inserting, then deletes the old Markdown file. Reprocessing replaces, never appends.
Dedup by hash. save_upload rejects a file whose sha256 already exists in the same week (DuplicateSourceError → 409).
Deletes cascade manually (no FK cascade): deleting a subject/week/source/document removes child DB rows and unlinks files. Renaming a week (update_week) renames the directory and rewrites stored paths in the DB with SQL replace().
Markdown is sanitized (_sanitize_markdown strips control chars) on every read and write.
Week exports (export_week_markdown) concatenate documents, stripping each doc's frontmatter and inserting  markers; the .zip variant ships individual files.

Frontend

Next.js 14 App Router (frontend/app/), Tailwind, react-markdown + remark-gfm. All backend calls go through the single api object in frontend/lib/api.ts. API_URL resolves to http://127.0.0.1:8000 in dev (via NEXT_PUBLIC_API_URL) or /api in prod, where next.config.mjs rewrites() proxy /api/* to BACKEND_INTERNAL_URL. Pages mirror the data model: /, /subjects/[subjectId], /subjects/[subjectId]/weeks/[weekNumber], /documents/[documentId], /settings.

Deployment shape

Single container runs both processes: start-coolify.sh launches uvicorn on 127.0.0.1:8000 (internal only) and Next.js standalone on PORT (default 3000, public). /app/data must be a mounted volume or all subjects/documents/SQLite state are lost on redeploy. ffmpeg is required at runtime for video.

Conventions

UX, error messages, and generated content are in Spanish — preserve this. Source comments/identifiers are mixed Spanish/English; match the surrounding file.
The standalone estacion documentos.html is a browser-only prototype kept for reference behavior; the real app is backend/ + frontend/.

5.1 KiB Raw Permalink Blame History