# karthiksahe/rec-lab-record-generator architecture

> Architecture diagram of the GitHub repository karthiksahe/rec-lab-record-generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karthiksahe/rec-lab-record-generator
- Repository: https://github.com/karthiksahe/rec-lab-record-generator

## Overview

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

Main entry points: [`backend/app/api/documents.py`](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/api/documents.py) (Document lifecycle API), [`backend/app/services/document_service.py`](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/services/document_service.py) (Record compiler), [`backend/app/main.py`](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/main.py) (FastAPI application), [`frontend/src/pages/Dashboard.jsx`](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/frontend/src/pages/Dashboard.jsx) (Record dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_app_shell["Route shell &amp; guards<br/>React routes<br/>[App.jsx]"]
  node_auth_context["Session context<br/>Firebase/mock auth<br/>[AuthContext.jsx]"]
  node_dashboard["Record dashboard<br/>workflow UI<br/>[Dashboard.jsx]"]
  node_api_client["Authenticated API client<br/>HTTP client<br/>[api.js]"]
  node_pdf_viewer["PDF preview viewer<br/>PDF.js canvas<br/>[PdfViewer.jsx]"]
end

subgraph group_api["FastAPI backend"]
  node_fastapi_app["FastAPI application<br/>API host<br/>[main.py]"]
  node_auth_api["Auth endpoints<br/>API router<br/>[auth.py]"]
  node_document_api["Document lifecycle API<br/>API router<br/>[documents.py]"]
  node_auth_service["Firebase token verification<br/>auth service<br/>[auth_service.py]"]
  node_document_schema["Document input contract<br/>Pydantic schema<br/>[document.py]"]
end

subgraph group_generation["Document pipeline"]
  node_document_service["Record compiler<br/>DOCX generation"]
  node_docx_template["Lab record template<br/>DOCX template"]
  node_qr_generator["QR generator<br/>image utility<br/>[qr_generator.py]"]
  node_pdf_converter["LibreOffice converter<br/>PDF conversion<br/>[pdf_converter.py]"]
end

subgraph group_services["External services"]
  node_firebase{{"Firebase<br/>identity provider<br/>[firebase.js]"}}
  node_supabase_service["Supabase persistence<br/>storage/CRUD service"]
  node_supabase[("Supabase PostgreSQL &amp; storage<br/>database and object storage<br/>[schema.sql]")]
end

subgraph group_runtime["Deployment"]
  node_compose["Docker Compose<br/>service orchestration<br/>[docker-compose.yml]"]
  node_backend_image["Backend runtime<br/>Python + LibreOffice image"]
  node_frontend_image["Frontend runtime"]
end

node_app_shell -->|"provides session"| node_auth_context
node_app_shell -->|"protects route"| node_dashboard
node_auth_context -->|"authenticates with"| node_firebase
node_dashboard -->|"submits and manages records"| node_api_client
node_api_client -->|"JWT API requests"| node_fastapi_app
node_dashboard -->|"displays preview"| node_pdf_viewer
node_fastapi_app -->|"routes"| node_auth_api
node_fastapi_app -->|"routes"| node_document_api
node_auth_api -->|"verifies identity"| node_auth_service
node_document_api -->|"authorizes user"| node_auth_service
node_auth_service -->|"verifies bearer token"| node_firebase
node_document_api -->|"validates payload"| node_document_schema
node_document_api -->|"preview and generate"| node_document_service
node_document_service -->|"merges into"| node_docx_template
node_document_service -->|"embeds QR images"| node_qr_generator
node_document_service -->|"converts DOCX"| node_pdf_converter
node_document_api -->|"persists and retrieves"| node_supabase_service
node_supabase_service -->|"metadata and artifacts"| node_supabase
node_compose -->|"runs"| node_backend_image
node_compose -->|"runs"| node_frontend_image
node_frontend_image -.->|"serves client for"| node_fastapi_app
node_backend_image -.->|"provides LibreOffice"| node_pdf_converter

click node_app_shell "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/frontend/src/App.jsx"
click node_auth_context "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/frontend/src/contexts/AuthContext.jsx"
click node_dashboard "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/frontend/src/pages/Dashboard.jsx"
click node_api_client "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/frontend/src/services/api.js"
click node_pdf_viewer "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/frontend/src/components/PdfViewer.jsx"
click node_fastapi_app "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/main.py"
click node_auth_api "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/api/auth.py"
click node_document_api "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/api/documents.py"
click node_auth_service "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/services/auth_service.py"
click node_document_schema "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/schemas/document.py"
click node_document_service "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/services/document_service.py"
click node_docx_template "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/templates/Lab_Record_Template.docx"
click node_qr_generator "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/utils/qr_generator.py"
click node_pdf_converter "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/utils/pdf_converter.py"
click node_firebase "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/frontend/src/services/firebase.js"
click node_supabase_service "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/services/supabase_service.py"
click node_supabase "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/schema.sql"
click node_compose "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/docker-compose.yml"
click node_backend_image "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/Dockerfile"
click node_frontend_image "https://github.com/karthiksahe/rec-lab-record-generator/blob/main/frontend/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_shell,node_auth_context,node_dashboard,node_api_client,node_pdf_viewer toneBlue
class node_fastapi_app,node_auth_api,node_document_api,node_auth_service,node_document_schema toneAmber
class node_document_service,node_docx_template,node_qr_generator,node_pdf_converter toneMint
class node_firebase,node_supabase_service,node_supabase toneRose
class node_compose,node_backend_image,node_frontend_image toneIndigo
```

## Components

### React client

- [Route shell & guards](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/frontend/src/App.jsx): React routes · Composes providers, auth guard, and application routes. · `frontend/src/App.jsx`
- [Session context](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/frontend/src/contexts/AuthContext.jsx): Firebase/mock auth · Maintains user session and obtains identity tokens. · `frontend/src/contexts/AuthContext.jsx`
- [Record dashboard](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/frontend/src/pages/Dashboard.jsx): workflow UI · Collects data, previews records, and manages saved documents. · `frontend/src/pages/Dashboard.jsx`
- [Authenticated API client](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/frontend/src/services/api.js): HTTP client · Attaches Firebase JWTs to backend requests. · `frontend/src/services/api.js`
- [PDF preview viewer](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/frontend/src/components/PdfViewer.jsx): PDF.js canvas · Renders transient preview PDFs in the browser. · `frontend/src/components/PdfViewer.jsx`

### FastAPI backend

- [FastAPI application](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/main.py): API host · Configures CORS and registers auth and document routers. · `backend/app/main.py`
- [Auth endpoints](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/api/auth.py): API router · Synchronizes authenticated profiles. · `backend/app/api/auth.py`
- [Document lifecycle API](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/api/documents.py): API router · Provides preview, generation, listing, download, and deletion flows. · `backend/app/api/documents.py`
- [Firebase token verification](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/services/auth_service.py): auth service · `backend/app/services/auth_service.py`
- [Document input contract](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/schemas/document.py): Pydantic schema · `backend/app/schemas/document.py`

### Document pipeline

- [Record compiler](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/services/document_service.py): DOCX generation · Merges data, expands experiment rows, and applies Word compatibility adjustments. · `backend/app/services/document_service.py`
- [Lab record template](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/templates/Lab_Record_Template.docx): DOCX template · `backend/templates/Lab_Record_Template.docx`
- [QR generator](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/utils/qr_generator.py): image utility · Creates transparent QR images for repository URLs. · `backend/app/utils/qr_generator.py`
- [LibreOffice converter](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/utils/pdf_converter.py): PDF conversion · Converts generated DOCX to layout-faithful PDF. · `backend/app/utils/pdf_converter.py`

### External services

- [Firebase](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/frontend/src/services/firebase.js): identity provider · Authentication authority issuing bearer tokens. · `frontend/src/services/firebase.js`
- [Supabase persistence](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/app/services/supabase_service.py): storage/CRUD service · Stores artifacts, metadata, and download history with service-role access. · `backend/app/services/supabase_service.py`
- [Supabase PostgreSQL & storage](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/schema.sql): database and object storage · Holds document metadata and lab-records artifacts. · `backend/schema.sql`

### Deployment

- [Docker Compose](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/docker-compose.yml): service orchestration · Coordinates frontend and backend containers. · `docker-compose.yml`
- [Backend runtime](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/backend/Dockerfile): Python + LibreOffice image · `backend/Dockerfile`
- [Frontend runtime](https://github.com/karthiksahe/rec-lab-record-generator/blob/main/frontend/Dockerfile): Vite build + Nginx image · `frontend/Dockerfile`

## Connections

- Route shell & guards → Session context: provides session
- Route shell & guards → Record dashboard: protects route
- Session context → Firebase: authenticates with
- Record dashboard → Authenticated API client: submits and manages records
- Authenticated API client → FastAPI application: JWT API requests
- Record dashboard → PDF preview viewer: displays preview
- FastAPI application → Auth endpoints: routes
- FastAPI application → Document lifecycle API: routes
- Auth endpoints → Firebase token verification: verifies identity
- Document lifecycle API → Firebase token verification: authorizes user
- Firebase token verification → Firebase: verifies bearer token
- Document lifecycle API → Document input contract: validates payload
- Document lifecycle API → Record compiler: preview and generate
- Record compiler → Lab record template: merges into
- Record compiler → QR generator: embeds QR images
- Record compiler → LibreOffice converter: converts DOCX
- Document lifecycle API → Supabase persistence: persists and retrieves
- Supabase persistence → Supabase PostgreSQL & storage: metadata and artifacts
- Docker Compose → Backend runtime: runs
- Docker Compose → Frontend runtime: runs
- Frontend runtime → FastAPI application: serves client for
- Backend runtime → LibreOffice converter: provides LibreOffice