karthiksahe/rec-lab-record-generator

Purpose and Entry Points

This is a full-stack laboratory-record generator. Users authenticate, submit course/student/experiment data, and receive template-faithful DOCX and PDF records with QR codes for experiment repositories.

• Backend FastAPI application: backend/app/main.py

• Frontend React mount and route shell: frontend/src/main.jsx, frontend/src/App.jsx

• Container orchestration: docker-compose.yml

Frontend Application and Session Boundary

The Vite/React client provides authentication screens and a protected dashboard for input, preview, saved-record browsing, and downloads.

• Routes and provider/guard composition: frontend/src/App.jsx

• Session state and Firebase/mock-auth integration: frontend/src/contexts/AuthContext.jsx, frontend/src/services/firebase.js

• Dashboard workflow: frontend/src/pages/Dashboard.jsx

Firebase supplies identity tokens in normal operation; mock mode can use browser local storage. The frontend API client attaches JWTs to backend calls: frontend/src/services/api.js.

Preview Rendering Pipeline

The dashboard submits record payloads to the preview endpoint, which returns a transient PDF stream rather than persisting a document. The client renders it in a custom canvas-based PDF.js viewer, including responsive/high-DPI behavior and a CDN worker workaround.

• Viewer boundary: frontend/src/components/PdfViewer.jsx

• API router: backend/app/api/documents.py

• Document input contract: backend/app/schemas/document.py

This separates immediate visual validation from permanent generation and storage.

Backend API, Identity, and Authorization

FastAPI exposes authentication synchronization/profile and document lifecycle routes. Requests require Firebase bearer tokens; authenticated identity scopes document access and persistence.

• Application setup, CORS, and router registration: backend/app/main.py, backend/app/config.py

• Auth endpoints: backend/app/api/auth.py

• Firebase verification/auth service: backend/app/services/auth_service.py

Document Compilation Engine

The document service is the core generation stage: it merges submitted data into the base DOCX, duplicates experiment rows in memory, produces transparent QR images for GitHub URLs, and applies the Word page-border compatibility adjustment required by LibreOffice.

• Core template and generation logic: backend/app/services/document_service.py

• Source template: backend/templates/Lab_Record_Template.docx

• QR creation: backend/app/utils/qr_generator.py

The resulting DOCX is converted through headless LibreOffice for layout-faithful PDF output: backend/app/utils/pdf_converter.py.

Persistence and External Services

Supabase is both the PostgreSQL persistence layer and permanent artifact store. Generation uploads DOCX/PDF files to the lab-records bucket, stores document metadata, and supports per-user listing, detail, deletion, and download-history logging.

• Supabase CRUD/storage boundary: backend/app/services/supabase_service.py

• Database schema: backend/schema.sql

• Document route orchestration: backend/app/api/documents.py

Firebase is the authentication authority; Supabase service-role access supports backend writes that may bypass row-level security.

Runtime and Deployment Boundaries

The backend runs Python/FastAPI with LibreOffice available in its environment; the frontend builds as Vite static assets and is served by Nginx in its production container. Docker Compose coordinates both services.

• Backend runtime image and LibreOffice installation: backend/Dockerfile

• Frontend build/serving image: frontend/Dockerfile

• Multi-service deployment: docker-compose.yml

Environment-specific URLs, Firebase credentials, Supabase keys, template location, LibreOffice executable, and CORS origins are centralized by backend/app/config.py and the .env.example files.