Flashbook

Flashbook is a Flutter-based learning app that converts books and PDFs into swipeable, AI-generated learning cards with progress sync, visual generation, and cloud-backed user state.

What Flashbook Does

Upload a PDF (or choose a demo source).
Extract and chunk text.
Generate structured chapter cards using AI.
Render an Instagram-style vertical feed for reading.
Save progress and resume across sessions/devices.

Current Architecture (Implemented)

Production path:

Flutter app -> API Gateway -> Lambda handlers -> DynamoDB/S3/Cognito -> Gemini APIs

The repository also contains a local FastAPI backend for local/dev workflows.

Core Features

AI chapter summarization into structured learning cards.
Vertical reading feed with progressive loading.
PDF upload via presigned S3 URL.
Batch text extraction from S3-stored PDF pages.
On-demand AI image generation for visual blocks.
Reading progress sync and resume support.
Cognito-based auth with token refresh.
Library management (list, resume, delete books).
Bookmarks and notes support (notes backend exists; current UI uses local note persistence).

Tech Stack

Frontend:

Flutter
Provider (state management)
HTTP package
SharedPreferences

Backend (AWS path):

API Gateway (REST)
AWS Lambda (Python)
DynamoDB
S3
Cognito
CloudWatch logs

AI:

Google Gemini text model (summary generation)
Google Gemini image model (image generation)

Local/dev backend:

FastAPI + Uvicorn
Pydantic
pypdf

Repository Structure

flashbook/
├── lib/                          # Flutter app
│   ├── screens/                  # UI screens
│   ├── state/                    # Providers
│   ├── services/                 # API/auth/storage services
│   ├── models/                   # Data models
│   └── widgets/                  # Reusable UI widgets
├── backend/
│   ├── main.py                   # FastAPI entrypoint (local mode)
│   ├── src/                      # FastAPI modules (api/core/services)
│   └── aws/
│       ├── template.yaml         # SAM infrastructure
│       ├── handlers/             # Lambda handlers
│       └── events/               # Local SAM test events
├── assets/                       # Static app assets
└── *.md                          # Design, analysis, architecture docs

API Surface (AWS)

Public endpoints:

GET /health
POST /auth/signup
POST /auth/login
POST /auth/verify
POST /auth/refresh

Protected endpoints (Cognito authorizer by default):

POST /extractText
POST /generateSummary
POST /generateImage
GET|POST|PUT|DELETE /notes/*
POST|GET|PUT|DELETE /books/*

Data Model Overview

DynamoDB tables:

flashbook-slides
PK: book_id
SK: chapter_hash
TTL: expires_at
Purpose: summary response cache
flashbook-notes
PK: note_id
GSI: book_id-index
Purpose: notes storage
flashbook-user-books
PK: user_id
SK: book_id
Purpose: user library metadata, progress, extraction status, image URL map

S3 buckets:

flashbook-pdfs-<account>: uploaded source PDFs
flashbook-images-<account>: generated images

Main User Flow

App launches and checks API health.
Auth session restore runs via refresh token.
User uploads PDF.
App requests upload URL (/books/upload) and uploads to S3.
Backend confirms and counts pages (/books/{id}/confirm).
App extracts first page batch (/extractText).
App generates chapter cards (/generateSummary) with cache support.
User reads in vertical feed; progress syncs (/books/{id}/progress).
Visual cards trigger lazy image generation (/generateImage).

Running the Flutter App

Prerequisites:

Flutter SDK (stable)
Android Studio/Xcode or connected device

Commands:

flutter pub get
flutter run

Backend URL config:

Production URL is configured in lib/services/api_config.dart.

Running Local FastAPI Backend (Optional)

Use this for local backend development/testing.

cd backend
python -m venv venv

# Windows
venv\Scripts\activate

pip install -r requirements.txt
python main.py

Open docs at:

http://localhost:8080/docs

Deploying AWS Backend (SAM)

Prerequisites:

AWS CLI configured
SAM CLI installed

cd backend/aws
sam build
sam deploy --guided

After deploy:

Copy ApiUrl from stack outputs.
Set/update prodUrl in lib/services/api_config.dart if needed.

Important Implementation Notes

Built vs documented target architecture
Implemented backend uses Gemini APIs directly.
Some docs mention Bedrock/CloudFront/Redis/X-Ray/analytics as future architecture targets.
Dual backend code paths
AWS Lambda path is the main production path.
FastAPI path remains for local/dev and migration support.
Notes behavior
Backend notes APIs are implemented.
Current app NoteProvider still stores notes locally in SharedPreferences.