How faresmallah/briefup works
BriefUp is a classic Java EE servlet application deployed on Apache Tomcat, with a server-rendered UI and a thin client-side layer. The architecture is split into presentation, request handling, domain model, persistence, and AI-assisted content generation.
The presentation layer lives under src/main/webapp. It mixes JSP (home.jsp, deck.jsp) and static HTML entry pages (login.html, signup.html, main.html), plus CSS and a small amount of JavaScript (home.js, deck.js) for interactive behavior. This suggests most page composition happens on the server, with JavaScript used for dynamic actions like deck editing or study flow.
HTTP routing is handled by servlets in com.briefup.controllers. Each servlet appears to own a focused use case: authentication (LoginServlet, SignupServlet, LogoutServlet), deck lifecycle (CreateDeckServlet, SaveDeckServlet, DeleteDeckServlet, DeleteDeckByIdServlet, ListDecksServlet, ListCardsServlet), study/session flows (StudySessionServlet, GetStatsServlet), and social/progression features (LeaderboardServlet, HomeServlet). For diagramming, these are the primary application entry points.
Authentication is enforced by AuthFilter, which likely guards protected routes and redirects unauthenticated users to login/signup. That makes session state an important boundary: public pages vs. authenticated study/deck management pages.
The domain layer is simple and explicit: User, Deck, Card, and UserStats. These objects represent the core data the application moves between controllers, DAOs, and JSPs. UserStats is especially important because it underpins study progress, quiz results, and leaderboard ranking.
Persistence is handled by DAO classes: UserDAO, DeckDAO, CardDAO, and UserStatsDAO. This is a direct JDBC-style architecture rather than an ORM-based one. DBConnection centralizes MySQL connectivity, so the DAO layer is the main boundary between application logic and the database.
The database is MySQL, bundled with the JDBC connector in WEB-INF/lib. That means the app is self-contained at deployment time, with database access managed inside the servlet container rather than through external persistence infrastructure.
AI flashcard generation is a distinct subsystem. AiFlashcardService in the service/AI packages indicates a service layer that calls the OpenAI API to generate flashcards, likely from uploaded PDF content. The presence of Apache PDFBox in WEB-INF/lib strongly suggests the upload flow parses PDFs locally, extracts text, and then sends it into the AI generation step.
The PDF upload path is therefore a multi-step pipeline: user uploads a PDF through UploadPdfDeckServlet, the server extracts document text, the AI service generates candidate flashcards, and the resulting deck/cards are persisted through the DAO layer. This is the most important cross-cutting data flow in the system.
Study mode and analytics form another connected subsystem. StudySessionServlet, GetStatsServlet, LeaderboardServlet, and UserStatsDAO together imply that quiz attempts and progress updates are stored server-side, then aggregated for stats and rankings. In the architecture diagram, this is the read/write loop from study activity back into persistent progress data.
The main external dependencies that materially affect the architecture are Tomcat for servlet hosting, MySQL for storage, OpenAI for flashcard generation, and PDFBox for document parsing. The app is packaged as a traditional WAR-style web application, with web.xml defining servlet/filter wiring and WEB-INF/lib carrying the runtime jars.
Overall, the repository follows a straightforward layered MVC-style design: browser UI → servlet controllers → domain objects/DAOs → MySQL, with an AI/document-processing branch feeding deck creation. The key boundaries to show are authenticated vs public routes, controller vs DAO separation, and the PDF-to-AI-to-deck pipeline.
Main entry points: AuthFilter.java Auth Filter · DeckDAO.java Deck DAO · DBConnection.java DB Connection · HomeServlet.java Home
Components 34
Presentation
Server-rendered pages and thin client scripts
- Home UI · Main authenticated home page
src/main/webapp/home.jsp - Deck UI · Deck editing and study page
src/main/webapp/deck.jsp - Login · Public sign-in page
src/main/webapp/login.html - Signup · Public account creation page
src/main/webapp/signup.html - Main Entry · Primary landing page
src/main/webapp/main.html - Home JS · Home-page interactions
src/main/webapp/js/home.js - Deck JS · Deck editing and study interactions
src/main/webapp/js/deck.js
Controllers
Servlet entry points and request routing
- Auth Filter · Protects authenticated routes
src/main/java/com/briefup/filters/AuthFilter.java - Login · Authenticates users
src/main/java/com/briefup/controllers/LoginServlet.java - Signup · Creates user accounts
src/main/java/com/briefup/controllers/SignupServlet.java - Logout · Ends the active session
src/main/java/com/briefup/controllers/LogoutServlet.java - Home · Builds the authenticated home view
src/main/java/com/briefup/controllers/HomeServlet.java - List Decks · Returns user decks
src/main/java/com/briefup/controllers/ListDecksServlet.java - Create Deck · Creates a new deck
src/main/java/com/briefup/controllers/CreateDeckServlet.java - Save Deck · Persists deck edits
src/main/java/com/briefup/controllers/SaveDeckServlet.java - Delete Deck · Deletes a deck
src/main/java/com/briefup/controllers/DeleteDeckServlet.java - List Cards · Loads cards for a deck
src/main/java/com/briefup/controllers/ListCardsServlet.java - Study Session · Tracks study attempts
src/main/java/com/briefup/controllers/StudySessionServlet.java - Stats · Returns progress metrics
src/main/java/com/briefup/controllers/GetStatsServlet.java - Leaderboard · Serves ranking view
src/main/java/com/briefup/controllers/LeaderboardServlet.java - Upload PDF · Starts PDF-to-flashcard flow
src/main/java/com/briefup/controllers/UploadPdfDeckServlet.java
Domain
Core application entities
- User · Authenticated account
src/main/java/com/briefup/models/User.java - Deck · Flashcard deck aggregate
src/main/java/com/briefup/models/Deck.java - Card · Single flashcard
src/main/java/com/briefup/models/Card.java - User Stats · Study progress and ranking data
src/main/java/com/briefup/models/UserStats.java
Persistence
DAOs and database connection boundary
- User DAO · User persistence access
src/main/java/com/briefup/dao/UserDAO.java - Deck DAO · Deck persistence access
src/main/java/com/briefup/dao/DeckDAO.java - Card DAO · Card persistence access
src/main/java/com/briefup/dao/CardDAO.java - Stats DAO · Study and leaderboard persistence
src/main/java/com/briefup/dao/UserStatsDAO.java - DB Connection · MySQL connection factory
src/main/java/com/briefup/db/DBConnection.java
AI Pipeline
PDF parsing and flashcard generation
- Flashcard AI · Generates flashcards from extracted text
src/main/java/com/briefup/ai/AiFlashcardService.java
External
Runtime and third-party dependencies
- Tomcat · Hosts the WAR application
- MySQL · Persistent data store
- OpenAI API · LLM-backed content generation
Connections 38
- Main Entry → Login: entry · Public landing path to authentication
- Main Entry → Signup: entry · Public landing path to account creation
- Home UI → Home: renders · Server builds the authenticated home page
- Deck UI → List Cards: loads · Deck page fetches cards for editing or study
- Home JS → List Decks: ajax · Client requests the user's decks
- Deck JS → Save Deck: ajax · Client saves deck changes
- Deck JS → Study Session: ajax · Client records study events
- Auth Filter → Home: guards · Protects authenticated entry points
- Auth Filter → List Decks: guards · Protects authenticated entry points
- Auth Filter → Create Deck: guards · Protects authenticated entry points
- Auth Filter → Save Deck: guards · Protects authenticated entry points
- Auth Filter → Delete Deck: guards · Protects authenticated entry points
- Login → User DAO: authenticates · Validates credentials against persisted users
- Signup → User DAO: creates · Persists new user accounts
- Logout → User: clears · Ends the session for the current user
- Home → Deck DAO: reads · Loads deck summaries for the home view
- List Decks → Deck DAO: reads · Fetches user decks
- Create Deck → Deck: builds · Creates a new deck object
- Save Deck → Deck: updates · Applies deck edits
- Delete Deck → Deck DAO: deletes · Removes deck records
- List Cards → Card DAO: reads · Loads cards for a deck
- Study Session → Stats DAO: writes · Stores study outcomes
- Stats → Stats DAO: reads · Returns aggregated user progress
- Leaderboard → Stats DAO: reads · Builds ranking data from stats
- Upload PDF → Flashcard AI: invokes · Starts document-to-flashcard generation
- Upload PDF → Deck DAO: persists · Stores the generated deck
- Flashcard AI → OpenAI API: calls · Sends extracted text to the LLM API
- Flashcard AI → Card: produces · Generates flashcard content
- Deck DAO → DB Connection: uses · Opens JDBC connections
- Card DAO → DB Connection: uses · Opens JDBC connections
- User DAO → DB Connection: uses · Opens JDBC connections
- Stats DAO → DB Connection: uses · Opens JDBC connections
- DB Connection → MySQL: connects · JDBC boundary to MySQL
- Home → User: uses · Builds user-aware home content
- Study Session → User Stats: updates · Transforms study attempts into progress data
- Stats → User Stats: returns · Serves progress metrics
- Leaderboard → User Stats: ranks · Orders users by progress
- Create Deck → Card: adds · Attaches cards to newly created decks