Architecture atlas
One learning system with two paths into Firebase.
Learn Center organizes courses, uploaded material, and full screen study cards. Students use a Next.js browser application. A separate agent tool server manages validated text cards through Firebase Admin. Both paths meet in the same course data.
System map
One data store, two execution paths
The browser reaches Firebase through client services. The agent reaches the same Firestore course records through a separate tool process and Firebase Admin.
Rendering architecture diagram
Browser interface
Pages and components
- Responsibility
- Present courses and learning material, collect user actions, and keep interaction state close to the page that owns it.
- Change effect
- A new learning activity usually begins here, then reaches a hook or service only when it needs remote data.
- Evidence
- Verified from the implemented App Router pages and their React components.
Browser state
Hooks and authentication
- Responsibility
- Coordinate asynchronous browser work and expose stable state to pages without placing persistence calls in every component.
- Change effect
- Changes to loading or authentication behavior affect every page that consumes the corresponding hook or context.
- Evidence
- Verified from the shared React hooks, authentication context, and protected route behavior.
Data access
Client services
- Responsibility
- Translate browser actions into Firebase operations and convert stored records into application types.
- Change effect
- A stored field or file lifecycle change must remain aligned with page inputs, shared types, and the agent path.
- Evidence
- Verified from the course, study card, and assignment services.
Managed platform
Firebase
- Responsibility
- Own identity, persistent learning records, and binary course material used by the browser application.
- Change effect
- Collection or storage path changes affect browser services, agent operations, deployed rules, and existing data.
- Evidence
- Verified from Firebase client initialization, Firebase Admin initialization, and every persistence call.
Separate process
Agent tool server
- Responsibility
- Let an AI client manage text study cards through validated operations backed by Firebase Admin.
- Change effect
- A shared card rule must remain consistent across the agent schemas, browser services, and stored documents.
- Evidence
- Verified from thirteen registered tool definitions and the Firebase Admin connection.
Deployment
Cloudflare delivery
- Responsibility
- Run the web application at the edge and serve its generated assets through the Worker binding.
- Change effect
- A Next.js feature or runtime API must be supported by the OpenNext adapter and Cloudflare compatibility settings.
- Evidence
- Verified from the Next.js, OpenNext, and Cloudflare Worker configuration.
Runtime flows
Follow complete actions across the system
Select a user action to see which boundary owns each step, what is written, and where partial failure can leave work behind.
How does the home page remain useful when Firebase is unavailable or empty?
Course discovery keeps a useful static fallback
Rendering flow diagram
The fallback preserves navigation, but changes made only in Firebase are unavailable while Firebase configuration or reads fail.
Verified from the home page, course hook, course service, and bundled subject registry.
What happens from opening a subject to flipping the active study card?
The study route separates remote data from local interaction
Rendering flow diagram
The browser receives the full card set before filtering and shuffling it locally.
Verified from the study route, card hook, card service, scroll hook, and card component.
How does an authenticated editor create a card with text and images?
Rich card creation writes files before metadata
Rendering flow diagram
An upload can succeed before the final Firestore write. A later failure can therefore leave an uploaded image without a card record.
Verified from the protected route, rich text editor, create page, shared card rules, and card service.
How does the application handle several uploaded files when one fails?
Assignment batches report partial success
Rendering flow diagram
A file reaches Storage before its Firestore metadata is written, so a metadata failure can leave an uploaded file behind.
Verified from the assignment page, upload component, assignment hook, and assignment service.
How does an AI client create cards without bypassing validation and duplicate checks?
Agent generated cards pass through preview before writing
Rendering flow diagram
The agent path supports text cards. Cards containing uploaded images remain the browser application responsibility because file cleanup must stay coordinated.
Verified from the registered MCP tools, shared schemas, normalization rules, and Firebase Admin data access.
Data ownership
Course documents organize every stored object
Firestore stores metadata and relationships. Firebase Storage holds uploaded images and files whose download addresses are referenced by those documents.
Rendering data model diagram
| Stored object | Purpose | Readers | Writers |
|---|---|---|---|
| Courses | Course identity, display name, semester placement, route identity, and origin. | Home navigation, subject pages, and the agent tool server. | Browser course service and confirmed agent operations. |
| Study cards | Question and answer content, publication state, images, source context, duplicate hashes, and verified topic links. | Study, edit, and agent context workflows. | Authenticated browser editors and validated agent imports. |
| Assignments | Uploaded file name, download address, uploader identity, and timestamps. | The assignment page and assignment hook. | Authenticated assignment uploads. |
| Teacher notes | Teacher supplied file names and download addresses. | The teacher notes page and hook. | Not present in the inspected repository. |
| Agent import runs | Requested, created, and skipped card counts with the generated card identifiers and rejection reasons. | The agent import history tool. | The bulk agent card creation operation. |
| Stored files | Study card images, assignment files, and teacher note files kept separately from Firestore metadata. | Browser pages through Firebase download addresses. | Browser card and assignment services. The teacher note writer is unknown. |
Change guide
Where a change begins and where it spreads
Each guide follows the architecture already present. The page does not introduce a new service layer or prescribe a replacement framework.
Add a subject activity
- Begin with the subject route and its visible navigation.
- Add a hook or service only when the activity needs persistent data.
- Preserve the subject code used by routes and stored course documents.
- Add a route test and a focused interaction test for the new activity.
Change study card data
- Begin with the shared card shape and validation rules.
- Update browser serialization, editing, rendering, and agent serialization together.
- Existing stored cards must still load when the new field is absent.
- Test validation, normalization, browser display, and agent import behavior.
Add another uploaded file type
- Begin with the closest existing upload service and choose a stable Storage path.
- Coordinate Storage upload, Firestore metadata, display, and cleanup.
- A stored record must point to the uploaded object, and failed writes need a cleanup decision.
- Test file limits, partial failure, metadata writing, and object cleanup.
Add an agent operation
- Begin with one narrow tool input and reuse the shared validation rules.
- Keep browser and agent representations aligned when both touch the same data.
- Destructive changes require confirmation and generated cards require previewable validation.
- Test the shared rule and the structured tool result before enabling writes.
Change deployment behavior
- Begin with the OpenNext and Cloudflare Worker configuration.
- Confirm that the Next.js runtime feature is supported by the adapter and compatibility mode.
- Static assets and the Worker entry must remain available through the configured binding.
- Build and preview the Worker before any deployment request.
Evidence boundaries
What the repository proves and what it cannot
Unknown behavior is named instead of inferred. Confirmed gaps describe visible behavior at the inspected revision, not a proposed production promise.
Unknown
Production Firebase rules are outside the repository
The inspected source contains browser authentication and protected routes but no deployed Firestore or Storage rule files.
Consequence The source proves which checks the interface performs. It does not prove which direct Firebase requests production rules permit.
Unknown
Teacher note creation occurs elsewhere
The browser reads teacher note metadata, but the inspected source contains no upload page or write service for teacher notes.
Consequence The atlas can show how teacher notes are consumed but cannot identify the system that creates them.
Confirmed gap
Two visible learning links have no implemented page
Subject navigation includes Personal Notes and Textbook, while the inspected route tree contains no matching pages.
Consequence Selecting either link reaches the Next.js not found result at the inspected revision.
Coverage boundary
Automated tests concentrate on shared rules
The current suite covers schemas, normalization, extraction, prompts, and card interaction styles more deeply than live Firebase services and page flows.
Consequence The architecture is supported by source inspection, but several runtime integrations still require browser and service level coverage.
Evidence index
Every public claim has an inspected source area
The Learn Center repository is private. This public index names inspected responsibilities without publishing source paths, code excerpts, or configuration values.
The browser application uses one shared authentication provider.
- Inspected area
- Application root and authentication context
- Public conclusion
- Every page receives the same Firebase user state and sign in actions.
Course navigation can fall back to bundled data.
- Inspected area
- Home route, course hook, course service, and subject registry
- Public conclusion
- The visible course list remains available when remote courses cannot be loaded.
Study card files and metadata have separate lifecycles.
- Inspected area
- Card creation, update, deletion, Firebase Storage, and Firestore operations
- Public conclusion
- Images are stored as files while card records retain their download addresses and display order.
Assignment uploads preserve partial results.
- Inspected area
- Assignment page, upload component, hook, and service
- Public conclusion
- One failed file does not erase successful files from the same batch.
The agent path is a separate process with thirteen tools.
- Inspected area
- Tool registrations, shared schemas, and Firebase Admin initialization
- Public conclusion
- AI operations do not run through a Next.js route and converge with the browser at Firestore.
Agent imports validate before writing.
- Inspected area
- Preview, duplicate detection, batch creation, and import history behavior
- Public conclusion
- Accepted cards and the import record are committed together after invalid or duplicate proposals are identified.
The Next.js application runs as a Cloudflare Worker.
- Inspected area
- Next.js, OpenNext, and Cloudflare configuration
- Public conclusion
- OpenNext produces the Worker entry and static asset directory used for delivery.
No architecture item matches that search.