LecteurAidewiki

LecteurAide

From the LecteurAide wiki

LecteurAide is a full-stack application that ingests French book PDFs, processes them with Google's Gemini models, and presents them in a reading interface with translations, vocabulary extraction and comprehension questions. The backend extracts text from PDFs, segments narratives into scenes using Gemini, translates French to English via Google Cloud Translation, and stores everything in a database; the frontend provides pages to upload books, browse a library, and read scenes with interactive features. The application is built in three layers: Book management handles the REST API for upload and retrieval, Content processing transforms PDFs into structured scenes and learning materials, and Data storage persists everything as ORM entities.

flowchart LR
  n1[["Book management"]]
  n2[["Content processing"]]
  n3[["Data storage"]]
  n2 -->|"6 calls, 2 imports"| n3
  n3 -->|"5 calls, 3 imports"| n2
  n3 -->|"4 calls, 3 imports"| n1
  n2 -->|"3 calls, 3 imports"| n1
  n1 -->|"1 call, 3 imports"| n2
  n1 -->|"3 imports"| n3
Each box is a feature; an arrow points from the feature whose code calls or imports to the one it uses.

Purpose and features

Users can upload a French PDF book with a title to the upload endpoint, which streams progress events as the backend processes the document.[1] (see Book management) Users can browse a library of ingested books and retrieve the full content of a book including scenes, sentences, their English translations, vocabulary items and comprehension questions.[2][3] (see Book management) The reader interface displays one scene at a time in a paper-inspired layout, allows clicking sentences to reveal translations, highlights key vocabulary and presents scene-specific comprehension questions.[4] (see Book management)

Layers

  • The API layer (Book management) exposes REST routes under /books that handle PDF uploads with streaming progress events, list processed books, and retrieve full book content with scenes, sentences, translations, vocabulary and questions.[5]
  • The processing layer (Content processing) transforms uploaded PDFs into structured data by extracting text, splitting into sentences, translating French to English, using Gemini to segment narratives into scenes, and extracting vocabulary and comprehension questions.[6]
  • The persistence layer (Data storage) stores books, scenes, sentences, vocabulary items and comprehension questions as SQLAlchemy ORM entities, supporting SQLite by default and any SQLAlchemy-compatible database through configuration.[7]
  • The frontend layer provides three pages: an upload form at /, a library browser at /library, and a per-book reader at /books/[bookId].[8]

Request paths

  • When a user uploads a PDF, the request enters the API through POST /books/upload in Book management, which calls IngestionPipeline from Content processing; the pipeline extracts PDF text, segments it into scenes with Gemini, translates sentences and creates vocabulary and question records via Data storage ORM entities, and returns a book_id to the client via server-sent events.[1][9][10]
  • When a user retrieves a book, the request to GET /books/{book_id} in Book management queries Data storage for the Book entity and its related scenes, sentences, vocabulary and questions, which are serialized and returned to the frontend.[11][12]

Feature dependencies

  • Content processing depends on Data storage to persist created books, scenes, sentences, vocabulary items and questions; it imports the ORM entities and calls methods on them during ingestion.[13]
  • Data storage depends on Book management for session management through get_session(), which provides database connections to API routes.[14][15]
  • Book management depends on Content processing to ingest and process uploaded PDFs; the API route imports IngestionPipeline and calls it to transform document content.[9]
  • The test suite in Data storage imports IngestionPipeline from Content processing to verify that narrative headings influence scene titles.[16][17]

References

  1. ^ a b README.md:L44@a9ffb3b
  2. ^ README.md:L45-46@a9ffb3b
  3. ^ README.md:L79-80@a9ffb3b
  4. ^ README.md:L80@a9ffb3b
  5. ^ README.md:L42-46@a9ffb3b
  6. ^ README.md:L3@a9ffb3b
  7. ^ README.md:L48@a9ffb3b
  8. ^ README.md:L76-80@a9ffb3b
  9. ^ a b backend/app/api/books.py:L20-22@a9ffb3b
  10. ^ backend/app/services/pipeline.py:L8-11@a9ffb3b
  11. ^ README.md:L46@a9ffb3b
  12. ^ backend/app/api/books.py:L19-21@a9ffb3b
  13. ^ backend/app/services/pipeline.py:L5-8@a9ffb3b
  14. ^ backend/app/db/session.py:L6@a9ffb3b
  15. ^ backend/app/api/books.py:L19@a9ffb3b
  16. ^ backend/tests/test_heading_titles.py:L16@a9ffb3b
  17. ^ backend/tests/test_heading_titles.py:L69@a9ffb3b (HeadingTitleTests.test_headings_influence_scene_titles)

This page was last edited on 2 November 2025, at commit a9ffb3b.