FlashBook: a serverless pipeline that turns PDFs into learning cards

FlashBook turns a book or PDF into a vertical feed of short, swipeable cards, the way a short-video app works. Each card has a headline, a few sentences and sometimes a generated picture, and your place in the book follows you between phones. I built it as a Flutter app on top of a serverless AWS backend, and this post walks that backend one requirement at a time: sign-in, a PDF upload that never touches a function, the summary call that costs money, pictures, and the notes and progress that make it resumable. It also covers the places where it is still wrong.

The board below is everything the backend is made of. I will keep coming back to it, one piece at a time.

One request, end to end#

The request that matters most is opening a chapter. It crosses every layer: the app, the gateway, the token check, the cache, the model and back. Everything else in the system exists to make this one call possible, cheap or repeatable.

The app does not send a whole book. It splits the extracted text into chunks of about 5,000 characters, never fewer than 2,000 unless it is the last, and keeps at most 15 of them. Each chunk becomes a chapter. That keeps every model prompt small enough to finish inside the 29 second ceiling and keeps the number of model calls per book bounded.

Understand the problem#

I wanted a way to read a long PDF without it feeling like homework. The first version was a Flutter client with a FastAPI backend that I ran on my laptop. The version I took through the AWS-backed AI for Bharat hackathon rounds replaced that backend with the serverless stack in this post, and the FastAPI code stayed in the repo for local work.

Functional requirements#

1. A user can sign up, verify an email, sign in and stay signed in.
2. A user can upload a PDF and see it in a library.
3. The system turns a chapter of text into a short run of cards.
4. Some cards carry a generated picture.
5. A user can bookmark, take notes and resume at the same card on another device.

Non-functional requirements#

1. Safe by default. A route someone forgets to think about must require a login, not allow anyone.
2. Large files stay off the API. API Gateway and Lambda both have request payload limits far below a textbook PDF.
3. Bounded model cost. The same text should never be summarised twice in a day, and one chapter should never produce an unbounded number of calls.
4. Degrade, do not break. A model failure or a cache failure must still leave the reader with something to swipe.
5. Finish inside 29 seconds. That is the API Gateway integration timeout, so every function has to answer within it.
6. Resumable. Position and pictures must restore on a device that has never seen the book.

Requirements: sign in, upload, cards, pictures, notes + progress
Hard limits : 29 s per call, 15-minute upload URL, 24 h cache
Nothing built yet. Next: the entities and the interface.

The set-up#

Core entities#

The backend names five things: a user, a book, a note, a PDF and an image. A book belongs to a user and points at one PDF. Chapters and cards are shaped by the model's answer and cached as one JSON document per chapter, so the backend never stores a card as its own row.

The interface#

The API is a plain REST surface. The auth routes and health are public. Everything else carries a Bearer token.

Public (Authorizer: NONE)
GET    /health
POST   /auth/signup      /auth/verify      /auth/login      /auth/refresh

Protected (Cognito authorizer by default)
POST   /books/upload                 -> { book_id, upload_url, s3_key }
POST   /books/{book_id}/confirm      -> { total_pages, status: "ready" }
GET    /books                        -> { books: [...] }
PUT    /books/{book_id}/progress     -> chapter, block, percent, image_urls
DELETE /books/{book_id}
POST   /extractText                  { s3_key, start_page, page_count }
POST   /generateSummary              { text_chunk, book_id, chapter_title, mode }
POST   /generateImage                { prompt, style, book_title }
GET    /notes/   /notes/book/{id}    POST /notes/create
PUT    /notes/{id}     DELETE /notes/{id}

The data model#

State is split by access pattern. The slides table is a pure cache and expires on its own. The user-books table is the library and the reading position. The notes table has a secondary index on the book. A second, 89-line template hosts the Flutter web build on S3 behind CloudFront; it is separate from the API stack.

Build it one requirement at a time#

Each board below keeps what the earlier ones built in grey and lights up the new parts. The numbers on the edges match the list under each board.

Requirement 1: sign in#

Cognito does the credential work and the auth function is a thin wrapper around it: sign_up, confirm_sign_up and initiate_auth with USER_PASSWORD_AUTH for login and REFRESH_TOKEN_AUTH for renewal. The password policy asks for eight characters, a lowercase letter and a number. Instead of attaching an authorizer to each route, I set it as the API default and opted the public routes out, so a route I forget is protected, not open.

Auth:
  DefaultAuthorizer: CognitoAuthorizer
  AddDefaultAuthorizerToCorsPreflight: false
  Authorizers:
    CognitoAuthorizer:
      UserPoolArn: !GetAtt CognitoUserPool.Arn

1. The app posts email and password to /auth/login.
2. The route has Authorizer: NONE, so the gateway forwards it to the auth function.
3. The function calls Cognito and returns an ID token, an access token and a refresh token.

The app keeps the tokens in SharedPreferences and, on launch, calls /auth/refresh with the stored refresh token to restore a session. Later requests send the ID token as a Bearer header and the gateway validates it before any function runs.

Requirement 2: upload a PDF#

A function that receives a whole PDF through the gateway is slow and expensive, so POST /books/upload does not take the file. It creates a row with status uploading and returns a presigned S3 PUT URL. The app uploads straight to S3, then calls /books/{id}/confirm, where the function reads the object back and counts pages with pypdf. Every key is namespaced by user id: users/{user_id}/books/{book_id}/{filename}.

1. The app asks the gateway for an upload.
2. The gateway routes it to the books function.
3. The function writes the book row and returns the signed URL.
4. The app puts the bytes straight into the PDF bucket.
5. On confirm, the function reads the object, counts pages and flips the status to ready.

Requirement 3: turn text into cards#

Two functions share the work. extractText reads a page range from S3 (start_page and a default page_count of 50) and returns text plus a has_more flag, so a big book is read in batches. generateSummary turns one chunk into cards.

1. The app asks for a page range of text.
2. The extract function reads that range from the PDF bucket.
3. The app sends one chunk to the summary function.
4. The function reads or writes the slides table by book and hash.
5. On a miss it asks Gemini for JSON.

The prompt is one narrator persona that asks for five to eight slides of types like scene, reveal, emotion, insight, quote and visual. The API has a mode field (chapter, concept or law) that changes one instruction line, but the app always sends chapter. The Study and Read chips on the onboarding screen are copy only and are not wired to anything.

Requirement 4: pictures on some cards#

The summary marks at most two blocks per chapter with an image_prompt. The app then calls /generateImage for those blocks. The function asks a Gemini image model for a picture, writes the PNG to the image bucket under generated/{uuid}.png and returns a presigned GET URL valid for seven days. The app waits for the first chapter's pictures before it opens the feed, then generates later chapters' pictures in the background with a short pause between calls.

1. The app sends the prompt, a style and the book title.
2. The function asks the Gemini image model for a picture and decodes the inline bytes.
3. It writes the PNG to the image bucket and returns a presigned URL.

Here is what the result looks like in the app, on real phone screenshots.

Requirement 5: notes and progress#

Progress is a PUT /books/{id}/progress that stores the chapter index, block index, percent, extraction status and a map of block id to image URL. That last field is what lets a second phone show the same pictures without regenerating them. Notes have their own function and table: create, read, update, delete and a list by book. The app's notes screen still stores notes locally in SharedPreferences, so this backend is built but not yet connected.

1. The app posts or edits a note.
2. The notes function writes one item keyed by note id.
3. As the reader moves, the app puts progress to the books route.
4. The function updates the book row, including the image URL map.

Deep dives#

Deep dive 1: presigned uploads and one signed header#

Deep dive 2: caching the expensive call#

Deep dive 3: making model output safe to render#

Deep dive 4: living inside a rate limit#

Deep dive 5: errors that never reach your code#

The final design#

Here is the whole board again, used by one reader opening a book on a phone that has never seen it. Every number is a request the app makes in the first few seconds.

1. The app starts and finds a stored refresh token.
2. It posts the token to /auth/refresh through the open route.
3. The auth function exchanges it with Cognito for fresh tokens.
4. The app calls GET /books with the new ID token.
5. The books function queries by user_id and returns each book's chapter, block and image URL map.
6. The app resends the current chapter's text to the summary function.
7. The slides table returns the cards if they are less than a day old; otherwise Gemini regenerates them.
8. The app loads each picture from its stored presigned URL, as long as the seven days have not passed.

What I would change#

• Scope notes by user. A note item has no user_id. Any signed-in user can read, edit or delete a note if they know its id, and the list-all route scans the whole table. The notes need the Cognito sub in the key and in every query.
• Do not fall back to "anonymous". The books and notes functions return the user id anonymous when the authorizer claims are missing. A missing claim should be a 401, not a shared bucket of data.
• Meter the model on the server. A per-user quota, or a queue with a rate limiter in front of Gemini, replaces the 13 second delay that only the client enforces.
• Widen the cache key. Hash the text together with the mode and the model name, so a prompt or model change cannot serve old cards.
• Move secrets out of the environment. The Gemini key is a NoEcho parameter copied into every function's environment, and the app's tokens sit in SharedPreferences. Secrets Manager for the two functions that need the key, and the keystore on the phone, are smaller blast radii.
• Retire the dual backend and fix the design doc. The FastAPI path and the Lambda path implement the same contract and will drift, and design.md still describes Bedrock, Titan, Redis and CloudFront. The shipped app calls Gemini.

Test yourself#