{ "project_id": "proj_2acdeb3f91", "business_idea": "want to build a platform called StudyFlow, an AI-powered university study management platform.Students can create an account, add their university courses, upload lecture notes and PDFs, and organize their study schedule. The platform uses AI to summarize uploaded materials, generate quizzes and flashcards, and answer questions based on the student's uploaded content.Students should have a personalized dashboard showing their courses, upcoming exams, assignments, and study progress. The system should recommend what they should study based on upcoming deadlines, previous performance, and available study time.Professors should be able to create courses, upload materials, publish announcements, and view general student performance statistics.The platform should support authentication with email/password and Google login. Students and professors have different permissions.The system should use a relational database for users, courses, enrollments, assignments, exams, study sessions, and progress. Uploaded documents should be stored separately, and an AI/RAG system should retrieve relevant content when answering questions.I want the application to be a web platform with a React frontend and Python/FastAPI backend. The AI services should be separated from the main backend so they can scale independently.The system should be containerized with Docker and have a CI/CD pipeline. It should be designed to support thousands of concurrent students and should include logging, monitoring, secure authentication, rate limiting, and database backups.", "problem": "University students need one place to organize courses, lecture materials, deadlines, and study time, and to get AI help grounded in their own content; professors need to share materials, announce updates, and see general student performance.", "target_users": [ "University students", "University professors", "Platform administrators" ], "user_roles": [ "student", "professor", "admin" ], "business_goals": [ "Help students organize coursework and study more effectively with AI tools grounded in uploaded materials", "Give professors a way to publish course content and announcements and view aggregate student performance" ], "core_features": [ "Student account creation", "Open student self-registration", "Add and organize university courses", "Enroll in professor-created courses via public search or course code", "Create personal private courses for individual study", "Upload lecture notes and PDFs", "Study schedule management", "Personalized dashboard with courses, upcoming exams, assignments, and study progress", "AI summaries of uploaded materials", "AI-generated quizzes and flashcards", "Q&A over the student's uploaded content via RAG", "Study recommendations based on upcoming deadlines, previous performance, and available study time", "Performance tracking using quiz scores, flashcard mastery, study time, assignment completion, and exam results", "Professor course creation", "Professor material uploads", "Professor announcements", "Professor-created assignments and exams in official courses", "Student-created assignments and exams in personal courses", "Professor view of aggregate student performance statistics only", "Email/password authentication", "Google login", "Manual admin verification of professor accounts before professor permissions are granted" ], "scope": "Web platform covering student study management (courses, uploads, schedule, dashboard, AI study tools, recommendations) and professor course operations (materials, announcements, assignments, exams, aggregate performance). Students can use both shared professor courses and private personal courses. Native mobile apps are not in scope.", "constraints": [ "Relational database for users, courses, enrollments, assignments, exams, study sessions, and progress", "Uploaded documents stored separately from the relational database", "AI/RAG services separated from the main backend so they can scale independently", "Designed for thousands of concurrent students", "Logging, monitoring, secure authentication, rate limiting, and database backups", "Professors must not access private materials uploaded by individual students", "Professor permissions are granted only after manual admin verification" ], "assumptions": [ "No payments, subscriptions, or in-app purchases are in the initial product", "The platform is open for student signup rather than limited to a single university", "Students, professors, and admins use the same web app with different permissions after login", "A bootstrap/seeded admin account is used to perform professor verification", "Enrollment via public search or course code does not require additional professor approval", "Students complete assignments and take exams on the platform so completion and results can be recorded", "A conventional relational database such as PostgreSQL is acceptable", "Object storage will hold uploaded files; embeddings/index live with the AI/RAG service", "Announcements are shown in the product UI; email or push delivery is not required for v1", "Personal courses are visible only to the student who created them", "Student RAG/Q&A is grounded in that student's private uploads plus official materials of enrolled courses, never other students' private files", "Available study time can be captured as a student-provided weekly or daily study-hours setting if not specified otherwise", "An OpenAI-compatible LLM/embedding API is acceptable for summaries, quizzes, flashcards, and RAG" ], "integrations": [ "Google OAuth", "AI/RAG retrieval over uploaded documents" ], "security_requirements": [ "Secure authentication", "Rate limiting", "Role-based access so students, professors, and admins have different permissions", "Professor verification by an admin before elevated permissions", "Student private uploads are isolated from professors and from other students" ], "performance_requirements": [ "Support thousands of concurrent students", "AI services must scale independently from the main backend" ], "deployment_requirements": [ "Docker containerization", "CI/CD pipeline", "Logging and monitoring", "Database backups" ], "technology_preferences": [ "React frontend", "Python/FastAPI backend", "Relational database", "Separate document/object storage", "Separate AI/RAG service", "Docker" ], "auth_requirement": "Email/password and Google login. Anyone can register as a student. Professor accounts require manual verification by an admin before professor permissions are granted.", "authorization_requirement": "Students, professors, and admins have different permissions. Students can enroll in official courses via public search or a course code, create private personal courses, upload materials, manage schedules, create assignments and exams in personal courses, complete assignments/exams, and use AI study tools. Professors can create official courses, upload official materials, publish announcements, create assignments and exams in official courses, and view aggregate performance statistics only. Professors must not see private materials uploaded by individual students. Admins can verify professor accounts.", "payment_requirement": "None; billing is not part of the described product", "notification_requirement": "Professors can publish announcements that are visible in the product UI; email, push, or SMS delivery is not specified and is assumed out of scope for v1", "business_analysis": null, "requirements": { "functional_requirements": [ "FR-01: Unauthenticated users can self-register a student account using email and password; new accounts receive the student role by default.", "FR-02: Registered users can authenticate with email and password.", "FR-03: Users can authenticate using Google OAuth.", "FR-04: After login, students, professors, and admins use the same web application with role-based permissions.", "FR-05: A user may request professor status; professor permissions are granted only after an admin manually verifies the account.", "FR-06: An admin can verify professor accounts and thereby grant professor permissions.", "FR-07: Verified professors can create official courses, including a public listing and a course code that students can use to enroll.", "FR-08: Students can discover official courses via public search and enroll without additional professor approval.", "FR-09: Students can enroll in an official course by entering a course code without additional professor approval.", "FR-10: Students can create personal private courses that are visible only to the creating student.", "FR-11: Students can add, view, and organize their courses, including official enrollments and personal courses.", "FR-12: Students can upload lecture notes and PDF documents associated with their courses; student private uploads are stored separately from the relational database.", "FR-13: Verified professors can upload official materials to official courses they own.", "FR-14: Verified professors can publish announcements on official courses they own; enrolled students can view those announcements in the product UI.", "FR-15: Verified professors can create, update, and publish assignments and exams in official courses they own.", "FR-16: Students can create assignments and exams in personal courses they own.", "FR-17: Students can complete assignments and take exams on the platform; the system records completion status and results.", "FR-18: Students can create and manage a study schedule of study sessions.", "FR-19: Students can set available study time as a weekly or daily study-hours preference used by recommendations.", "FR-20: Authenticated students receive a personalized dashboard showing their courses, upcoming exams, upcoming assignments, and study progress.", "FR-21: Students can request an AI-generated summary of an uploaded material they are authorized to access.", "FR-22: Students can generate AI quizzes from uploaded materials they are authorized to access and take those quizzes; quiz scores are recorded.", "FR-23: Students can generate AI flashcards from uploaded materials they are authorized to access and review them; flashcard mastery is recorded.", "FR-24: Students can ask questions and receive answers grounded via RAG in that student's private uploads plus official materials of courses they are enrolled in, and never in other students' private files.", "FR-25: The system recommends what a student should study based on upcoming deadlines, previous performance, and the student's available study time.", "FR-26: The system tracks student performance using quiz scores, flashcard mastery, study time from study sessions, assignment completion, and exam results.", "FR-27: Verified professors can view aggregate student performance statistics for official courses they own and cannot view individual students' private uploaded materials.", "FR-28: Professors cannot access private materials uploaded by individual students, including students enrolled in their courses.", "FR-29: The system persists users, courses, enrollments, assignments, exams, study sessions, and progress in a relational database.", "FR-30: Uploaded documents are stored in object storage separate from the relational database; embeddings and retrieval indexes are maintained by a dedicated AI/RAG service.", "FR-31: The main backend invokes a separately deployable AI/RAG service to summarize materials, generate quizzes and flashcards, and retrieve relevant content for Q&A." ], "non_functional_requirements": [ "NFR-01: The application is a web platform with a React frontend and a Python/FastAPI main backend; native mobile apps are out of scope.", "NFR-02: AI/RAG services are separated from the main backend so they can scale independently.", "NFR-03: The system is designed to support thousands of concurrent students.", "NFR-04: Authentication is implemented securely for email/password and Google OAuth sessions.", "NFR-05: API endpoints are rate limited to protect authentication and AI/study operations from abuse.", "NFR-06: Authorization is enforced server-side so students, professors, and admins cannot exercise another role's capabilities.", "NFR-07: Student private uploads are isolated from professors and from other students at storage and retrieval layers, including RAG.", "NFR-08: Application components are containerized with Docker.", "NFR-09: A CI/CD pipeline builds and deploys the containerized application.", "NFR-10: The system emits logs and exposes monitoring sufficient to observe application health and errors.", "NFR-11: Relational database backups are performed so user, course, enrollment, assignment, exam, study-session, and progress data can be recovered.", "NFR-12: Object storage holds uploaded files; the AI/RAG service owns embeddings and the retrieval index.", "NFR-13: An OpenAI-compatible LLM and embedding API is acceptable for summaries, quizzes, flashcards, and RAG." ], "user_stories": [ "As a university student, I want to create an account with email and password so that I can start organizing my courses and study materials.", "As a university student, I want to sign in with Google so that I can access StudyFlow without creating a separate password if I prefer Google login.", "As a university student, I want to search public official courses and enroll with a course code so that I can join professor-created courses without waiting for approval.", "As a university student, I want to create a private personal course so that I can organize individual study materials that only I can see.", "As a university student, I want to upload lecture notes and PDFs so that my materials are stored with my courses and available to AI study tools.", "As a university student, I want a personalized dashboard of my courses, upcoming exams, assignments, and study progress so that I can see what needs attention.", "As a university student, I want to manage my study schedule and available study hours so that I can plan when I will study.", "As a university student, I want AI summaries of my uploaded materials so that I can review content faster.", "As a university student, I want AI-generated quizzes and flashcards from my materials so that I can practice and track mastery.", "As a university student, I want to ask questions answered from my private uploads and official enrolled-course materials so that help is grounded in content I am allowed to use.", "As a university student, I want study recommendations based on deadlines, my performance, and available study time so that I know what to study next.", "As a university student, I want to complete assignments and take exams on the platform so that completion and results are recorded in my progress.", "As a university student, I want to create assignments and exams in my personal courses so that I can structure self-directed study.", "As a university professor, I want to request professor access and be verified by an admin so that I receive professor permissions only after review.", "As a university professor, I want to create official courses and upload official materials so that enrolled students can access course content.", "As a university professor, I want to publish announcements in the product UI so that enrolled students see course updates.", "As a university professor, I want to create assignments and exams in my official courses so that students can complete them on the platform.", "As a university professor, I want to view aggregate student performance statistics for my courses so that I can understand overall progress without seeing private student uploads.", "As a platform administrator, I want to manually verify professor accounts so that elevated professor permissions are granted only to approved users.", "As a platform administrator, I want role-based access control so that admin actions are limited to authorized admin accounts." ], "acceptance_criteria": [ "AC-01: A new user who registers with a unique email and password is created as a student and can sign in with those credentials.", "AC-02: A user with a valid Google account can sign in via Google OAuth and reach the web application in the appropriate role.", "AC-03: An unverified professor-requesting account cannot create official courses, upload official materials, publish announcements, create official assignments/exams, or view course performance statistics until an admin verifies the account.", "AC-04: After admin verification, the same account can perform professor capabilities listed in FR-07, FR-13, FR-14, FR-15, and FR-27.", "AC-05: A student can find an official course via public search, enroll, and immediately access that course without a professor approval step.", "AC-06: A student who enters a valid course code is enrolled in the corresponding official course without a professor approval step.", "AC-07: A student can create a personal course that does not appear in another student's course list or in professor views.", "AC-08: A student can upload a PDF or lecture-note file to a course they own or are enrolled in, and the file is stored in object storage rather than as a relational-database blob.", "AC-09: A professor can upload official materials to an official course they own, and enrolled students can access those official materials.", "AC-10: A professor cannot open, download, or retrieve via RAG a private file uploaded by a student.", "AC-11: A student cannot retrieve another student's private uploads via the UI or via RAG Q&A.", "AC-12: A professor announcement on an official course is visible in the product UI to enrolled students and is not required to be sent by email, push, or SMS.", "AC-13: A professor can create an assignment and an exam on an official course; enrolled students can complete them on the platform; completion and scores are stored.", "AC-14: A student can create an assignment and an exam on a personal course and complete them on the platform; completion and scores are stored.", "AC-15: The student dashboard displays the signed-in student's courses, upcoming exams, upcoming assignments, and study progress derived from tracked performance data.", "AC-16: Given an authorized uploaded document, a student can obtain an AI-generated summary of that document.", "AC-17: Given authorized materials, a student can generate a quiz, submit answers, and see a recorded quiz score that contributes to performance tracking.", "AC-18: Given authorized materials, a student can generate flashcards, review them, and have mastery recorded for performance tracking.", "AC-19: A student question is answered using retrieved passages only from that student's private uploads and official materials of enrolled courses.", "AC-20: Study recommendations change when upcoming deadlines, recorded performance, or the student's study-hours setting change, and each recommendation is explainable in terms of at least one of those three inputs.", "AC-21: Creating a study session records study time that appears in performance tracking.", "AC-22: A professor viewing performance for an official course sees aggregate statistics only and does not see another student's private files.", "AC-23: Unauthenticated requests to student, professor, or admin capabilities are rejected.", "AC-24: A student token cannot invoke professor or admin endpoints; a professor token cannot invoke admin verification; an admin can verify professor accounts.", "AC-25: Rate limiting rejects excess requests to authentication and AI endpoints according to configured limits.", "AC-26: Users, courses, enrollments, assignments, exams, study sessions, and progress are stored in the relational database and survive process restart.", "AC-27: The AI/RAG service can be deployed and scaled as a separate container from the FastAPI main backend.", "AC-28: Application images run via Docker; a CI/CD pipeline builds those images.", "AC-29: Logs and monitoring signals are produced for request handling and service health.", "AC-30: Database backup configuration exists so relational data can be restored." ], "constraints": [ "C-01: The product is a web platform only; native mobile apps are not in scope.", "C-02: Frontend must be React; main backend must be Python/FastAPI.", "C-03: Users, courses, enrollments, assignments, exams, study sessions, and progress must be stored in a relational database.", "C-04: Uploaded documents must be stored separately from the relational database.", "C-05: AI/RAG services must be separated from the main backend so they can scale independently.", "C-06: The system must be containerized with Docker and include a CI/CD pipeline.", "C-07: The system must include logging, monitoring, secure authentication, rate limiting, and database backups.", "C-08: The architecture must be designed to support thousands of concurrent students.", "C-09: Professors must not access private materials uploaded by individual students.", "C-10: Professor permissions are granted only after manual admin verification.", "C-11: Billing, payments, subscriptions, and in-app purchases are not part of the product.", "C-12: Email, push, and SMS notification delivery are out of scope for v1; announcements are in-product UI only.", "C-13: Authentication must support email/password and Google login." ], "assumptions": [ "A-01: No payments, subscriptions, or in-app purchases are in the initial product.", "A-02: The platform is open for student signup rather than limited to a single university.", "A-03: Students, professors, and admins use the same web app with different permissions after login.", "A-04: A bootstrap or seeded admin account is used to perform professor verification.", "A-05: Enrollment via public search or course code does not require additional professor approval.", "A-06: Students complete assignments and take exams on the platform so completion and results can be recorded.", "A-07: A conventional relational database such as PostgreSQL is acceptable.", "A-08: Object storage will hold uploaded files; embeddings and the retrieval index live with the AI/RAG service.", "A-09: Announcements are shown in the product UI; email or push delivery is not required for v1.", "A-10: Personal courses are visible only to the student who created them.", "A-11: Student RAG/Q&A is grounded in that student's private uploads plus official materials of enrolled courses, never other students' private files.", "A-12: Available study time is captured as a student-provided weekly or daily study-hours setting.", "A-13: An OpenAI-compatible LLM and embedding API is acceptable for summaries, quizzes, flashcards, and RAG.", "A-14: Official courses created by professors are publicly searchable and have a course code unless a later requirement states otherwise.", "A-15: 'Lecture notes and PDFs' means at least PDF plus common lecture-note document uploads; additional file types are unspecified and not required.", "A-16: Aggregate professor statistics are computed from enrolled students' recorded quiz scores, flashcard mastery, study time, assignment completion, and exam results without exposing private student files.", "A-17: Specific numeric SLAs (latency, uptime percentages, exact concurrent-user capacity, backup frequency, and rate-limit values) are unspecified and will be chosen during design without being treated as confirmed requirements.", "A-18: University identity (student ID, LMS, or SIS integration) is not required.", "A-19: Multi-language, accessibility standard, and data-residency/regulatory compliance beyond the stated security isolation and authentication rules are unspecified.", "A-20: Account recovery, email verification of student signup, and session timeout policy are unspecified and not required unless added later." ] }, "architecture": { "system_components": [ { "name": "React Web Application", "type": "frontend", "description": "Single-page web app used by students, professors, and admins. Provides email/password registration and login, Google sign-in, course search and enrollment, personal and official course workspaces, uploads, dashboard, study schedule, in-product announcements, assignments and exams, AI study tools, and admin professor verification. Role-based UI hides capabilities the authenticated role cannot use; authorization is always re-checked on the API.", "technology": "React 18 with Vite and React Router" }, { "name": "Nginx Reverse Proxy", "type": "infrastructure", "description": "TLS termination, static SPA hosting, and reverse proxy to FastAPI API replicas. Applies upload size limits and forwards client headers used for rate limiting and audit logs.", "technology": "Nginx" }, { "name": "StudyFlow API", "type": "backend", "description": "Primary FastAPI backend for identity, RBAC, professor verification, courses, enrollments, announcements, assignments, exams, submissions, study sessions, study-hours preferences, dashboard aggregation, performance tracking, and study recommendations. Persists relational data in PostgreSQL, issues pre-signed object-storage URLs after access checks, enqueues ingestion jobs, and invokes the separate AI/RAG service. Does not run embeddings or LLM inference.", "technology": "Python 3.12 FastAPI with Uvicorn, SQLAlchemy, Pydantic, and Alembic" }, { "name": "AI RAG Service", "type": "service", "description": "Separately deployable AI service invoked only by the StudyFlow API. Generates summaries, quizzes, and flashcards and answers student questions with RAG. Owns embeddings and the retrieval index. Retrieval applies ACL metadata so answers are grounded only in that student's private uploads plus official materials of enrolled courses, never other students' private files. Professors have no RAG path to student-private objects.", "technology": "Python 3.12 FastAPI with Uvicorn and an OpenAI-compatible client" }, { "name": "Document Ingestion Worker", "type": "service", "description": "Asynchronous workers that parse uploaded PDF and lecture-note files from object storage, chunk text, call the embedding API, and upsert vectors with owner, course, and visibility metadata. Scales independently of request-serving API replicas.", "technology": "Python ARQ workers on Redis" }, { "name": "PostgreSQL", "type": "database", "description": "Single primary relational database for users and roles, professor verification status, courses, enrollments and course codes, material metadata, announcements, assignments, exams, submissions and scores, quizzes, flashcard mastery, study sessions, study-hours preferences, and progress. Uploaded file bytes are not stored here.", "technology": "PostgreSQL 16" }, { "name": "Object Storage", "type": "infrastructure", "description": "Stores uploaded lecture notes and PDFs separately from PostgreSQL. Object keys are namespaced by visibility and owner. Downloads use short-lived pre-signed URLs issued only after RBAC checks.", "technology": "Amazon S3" }, { "name": "Vector Index", "type": "service", "description": "Retrieval index owned by the AI/RAG service. Stores embeddings and chunk metadata including user_id, course_id, material_id, and visibility. Queried with mandatory ACL filters so RAG cannot cross student-private boundaries.", "technology": "Qdrant" }, { "name": "Redis", "type": "infrastructure", "description": "Cache, rate-limit counters for authentication and AI endpoints, and job broker for document ingestion and long-running AI generation jobs.", "technology": "Redis 7" }, { "name": "Google Identity", "type": "external", "description": "Identity provider for Google login. The backend verifies Google ID tokens and links or creates a StudyFlow user with the default student role unless the account already has verified professor or admin privileges.", "technology": "Google OAuth 2.0 OpenID Connect" }, { "name": "LLM and Embedding Provider", "type": "external", "description": "OpenAI-compatible API used by the AI/RAG service and ingestion workers for embeddings, summaries, quiz and flashcard generation, and grounded Q and A completions.", "technology": "OpenAI-compatible LLM and embedding HTTP API" }, { "name": "CI CD Pipeline", "type": "infrastructure", "description": "Builds, tests, and publishes Docker images for the React static build, StudyFlow API, AI/RAG service, and ingestion workers, then deploys the containerized stack.", "technology": "GitHub Actions and Docker" }, { "name": "Observability Stack", "type": "infrastructure", "description": "Collects structured application logs, HTTP and worker metrics, and health checks so operators can observe errors, latency, queue depth, and service availability.", "technology": "Prometheus, Grafana, and Loki" }, { "name": "Database Backup Service", "type": "infrastructure", "description": "Automated PostgreSQL backups so users, courses, enrollments, assignments, exams, study sessions, and progress can be restored. Backup artifacts are stored in object storage with retention.", "technology": "pg_dump and WAL archiving to S3" } ], "communication": [ "Browsers load the React SPA over HTTPS from Nginx and send subsequent API calls as HTTPS JSON REST to Nginx, which proxies /api to StudyFlow API replicas.", "Unauthenticated clients call registration, email/password login, and Google OAuth endpoints. Authenticated clients send a Bearer JWT on every protected request.", "StudyFlow API reads and writes domain data to PostgreSQL over TLS using a connection pool. Material rows store object keys and ACL fields, not file bytes.", "After server-side authorization, StudyFlow API returns pre-signed S3 PUT and GET URLs. The browser uploads and downloads files directly to object storage over HTTPS.", "On successful upload, StudyFlow API enqueues an ingestion job on Redis. Document Ingestion Workers fetch the object from S3, embed chunks, and upsert into Qdrant with owner, course, and visibility metadata.", "For summaries, quizzes, flashcards, and RAG Q and A, StudyFlow API calls the AI/RAG service over internal HTTP that is not exposed publicly, passing authenticated user id, role, and authorized material or course scope. The AI/RAG service queries Qdrant with those ACL filters and calls the OpenAI-compatible LLM API over HTTPS.", "Study recommendations, dashboard aggregation, and professor aggregate statistics are computed by StudyFlow API from PostgreSQL performance records without sending private student files to professors or to the LLM.", "Google login uses OAuth 2.0 and OIDC. StudyFlow API verifies the ID token, upserts the user, and issues application JWTs.", "Services emit structured JSON logs and Prometheus metrics. Health checks flow from the load balancer to API, AI/RAG, workers, PostgreSQL, Redis, and Qdrant." ], "authentication": "Secure authentication with email/password and Google OAuth. Passwords are hashed with Argon2id and never stored in plaintext. Successful login issues a short-lived JWT access token and a rotating refresh token with user id and role claims (student, professor, admin) plus professor_verified. New self-registered accounts, including first-time Google users, receive the student role by default. A user may request professor status, which stores a pending verification record; professor permissions are granted only when a seeded admin account sets professor_verified. FastAPI dependencies reject missing, expired, or invalid tokens on all non-public endpoints.", "security": [ "Server-side RBAC so a student JWT cannot invoke professor or admin endpoints, a professor JWT cannot invoke admin verification, and unverified professor-requesting accounts cannot create official courses, official materials, announcements, official assignments or exams, or view course statistics.", "Student-private object keys and Qdrant payloads are isolated by owner_id and visibility=private; official materials use visibility=official and course_id. Pre-signed URLs and RAG queries both require these filters so professors and other students cannot open, download, or retrieve another student's private uploads.", "Rate limiting via SlowAPI backed by Redis on authentication endpoints and AI generation endpoints.", "TLS at the edge; internal service calls stay on the private network; S3 buckets block public ACLs; secrets come from environment or a secret manager, not container images.", "CORS limited to the web origin, security headers from Nginx, parameterized SQL via SQLAlchemy, and Pydantic validation of request bodies.", "Audit logging of admin professor verifications, role changes, and access-denied attempts on private materials." ], "scalability": [ "StudyFlow API replicas scale horizontally behind Nginx based on concurrent HTTP load so thousands of students can use dashboard, enrollment, schedule, and assignment flows without sharing processes with LLM work.", "AI/RAG service replicas and ingestion workers scale independently from the main backend so summarization, quiz generation, and embedding jobs do not starve interactive API traffic.", "Object storage takes bulk upload and download traffic; the API only authorizes and records metadata.", "Redis absorbs rate-limit state and job bursts; Qdrant scales with the AI/RAG service as document volume grows.", "PostgreSQL is the single primary database, accessed through pooling and indexed for enrollments, upcoming deadlines, and progress queries.", "Stateless JWT access tokens allow any API replica to authenticate a request; React static assets are cacheable at Nginx or a CDN." ], "technology_stack": { "React Web Application": "React 18, Vite, React Router", "Nginx Reverse Proxy": "Nginx", "StudyFlow API": "Python 3.12, FastAPI, Uvicorn, SQLAlchemy, Alembic, Pydantic, SlowAPI", "AI RAG Service": "Python 3.12, FastAPI, Uvicorn, OpenAI-compatible SDK", "Document Ingestion Worker": "Python ARQ, Redis broker", "PostgreSQL": "PostgreSQL 16", "Object Storage": "Amazon S3", "Vector Index": "Qdrant", "Redis": "Redis 7", "Google Identity": "Google OAuth 2.0 / OIDC", "LLM and Embedding Provider": "OpenAI-compatible LLM and embedding API", "CI CD Pipeline": "GitHub Actions, Docker", "Observability Stack": "Prometheus, Grafana, Loki", "Database Backup Service": "pg_dump and WAL archive to S3" }, "deployment_architecture": "Every application component is packaged as a Docker image and deployed by GitHub Actions after tests pass. Production runs in a single cloud region behind Nginx or a cloud load balancer terminating TLS. StudyFlow API, AI/RAG, and workers are separate services with independent replica counts. PostgreSQL 16 is the sole primary relational database, deployed as a managed instance or dedicated container with automated daily pg_dump plus WAL archiving to S3. Redis and Qdrant run as dedicated containers on the private network. Uploaded files live in a private S3 bucket; the AI/RAG service owns Qdrant embeddings. A bootstrap admin is seeded for professor verification. Observability agents scrape metrics and ship container logs. This layout supports thousands of concurrent students by scaling API and AI pools separately without a service mesh.", "mermaid_diagram": "flowchart TB\n Browser[Web Browser]\n React[React Web Application]\n Nginx[Nginx Reverse Proxy]\n API[StudyFlow API FastAPI]\n AIRAG[AI RAG Service]\n Worker[Document Ingestion Worker]\n PG[(PostgreSQL)]\n S3[S3 Object Storage]\n Redis[(Redis)]\n Qdrant[Qdrant Vector Index]\n Google[Google OAuth]\n LLM[OpenAI-compatible LLM API]\n Obs[Prometheus Grafana Loki]\n Backup[Database Backup Service]\n Browser -->|HTTPS SPA and REST| React\n React -->|HTTPS JSON JWT| Nginx\n Nginx --> API\n API -->|SQL TLS| PG\n API -->|pre-signed HTTPS| S3\n API -->|rate limits and jobs| Redis\n API -->|internal HTTP AI calls| AIRAG\n API -->|OAuth 2.0 OIDC| Google\n Redis --> Worker\n Worker --> S3\n Worker --> Qdrant\n Worker -->|embeddings| LLM\n AIRAG --> Qdrant\n AIRAG -->|authorized GET| S3\n AIRAG -->|summaries quizzes RAG| LLM\n API --> Obs\n AIRAG --> Obs\n Worker --> Obs\n Backup --> PG\n Backup --> S3" }, "database": { "database_technology": "PostgreSQL 16", "entities": [ { "name": "user", "description": "Authenticated StudyFlow account with email/password and/or Google OAuth identity, RBAC role, and professor verification flag. New self-registered accounts default to student.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "email", "type": "VARCHAR(255)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": true, "indexed": true }, { "name": "password_hash", "type": "VARCHAR(255)", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "google_sub", "type": "VARCHAR(255)", "primary_key": false, "foreign_key": null, "nullable": true, "unique": true, "indexed": true }, { "name": "display_name", "type": "VARCHAR(255)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "role", "type": "VARCHAR(32)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "professor_verified", "type": "BOOLEAN", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "is_active", "type": "BOOLEAN", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "updated_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "refresh_token", "description": "Rotating refresh tokens issued after email/password or Google login. Stores only a hash of the token.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "user_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "token_hash", "type": "VARCHAR(64)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": true, "indexed": true }, { "name": "expires_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "revoked_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "replaced_by_id", "type": "UUID", "primary_key": false, "foreign_key": "refresh_token.id", "nullable": true, "unique": false, "indexed": false }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "professor_verification", "description": "Admin-reviewed request for professor permissions. Professor capabilities are granted only after status becomes approved.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "user_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "status", "type": "VARCHAR(32)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "request_note", "type": "TEXT", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "review_note", "type": "TEXT", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "reviewed_by_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": true, "unique": false, "indexed": true }, { "name": "reviewed_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "updated_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "course", "description": "Official professor-owned publicly listed courses with enrollment codes, or student-owned personal private courses visible only to the owner.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "owner_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "title", "type": "VARCHAR(255)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "description", "type": "TEXT", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "visibility", "type": "VARCHAR(32)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "course_code", "type": "VARCHAR(32)", "primary_key": false, "foreign_key": null, "nullable": true, "unique": true, "indexed": true }, { "name": "is_listed", "type": "BOOLEAN", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "updated_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "enrollment", "description": "Student membership in an official course via public search or course code, without professor approval.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "course_id", "type": "UUID", "primary_key": false, "foreign_key": "course.id", "nullable": false, "unique": false, "indexed": true }, { "name": "student_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "method", "type": "VARCHAR(32)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "enrolled_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "material", "description": "Metadata for lecture notes and PDFs stored in object storage. Official materials belong to professor courses; private materials are isolated by uploader and never exposed to professors or other students.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "course_id", "type": "UUID", "primary_key": false, "foreign_key": "course.id", "nullable": false, "unique": false, "indexed": true }, { "name": "uploader_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "title", "type": "VARCHAR(255)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "original_filename", "type": "VARCHAR(512)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "content_type", "type": "VARCHAR(128)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "storage_bucket", "type": "VARCHAR(128)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "storage_key", "type": "VARCHAR(1024)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": true, "indexed": true }, { "name": "visibility", "type": "VARCHAR(32)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "byte_size", "type": "BIGINT", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "ingestion_status", "type": "VARCHAR(32)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "ingested_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "ingestion_error", "type": "TEXT", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "updated_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "announcement", "description": "In-product UI announcements published by verified professors on official courses they own.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "course_id", "type": "UUID", "primary_key": false, "foreign_key": "course.id", "nullable": false, "unique": false, "indexed": true }, { "name": "author_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "title", "type": "VARCHAR(255)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "body", "type": "TEXT", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "published_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "updated_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "assignment", "description": "Assignments created by professors on official courses or by students on personal courses, with draft/published lifecycle and due dates for dashboard and recommendations.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "course_id", "type": "UUID", "primary_key": false, "foreign_key": "course.id", "nullable": false, "unique": false, "indexed": true }, { "name": "creator_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "title", "type": "VARCHAR(255)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "description", "type": "TEXT", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "due_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": true }, { "name": "max_score", "type": "NUMERIC(8,2)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "status", "type": "VARCHAR(32)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "updated_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "exam", "description": "Exams created by professors on official courses or by students on personal courses, taken on the platform with recorded results.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "course_id", "type": "UUID", "primary_key": false, "foreign_key": "course.id", "nullable": false, "unique": false, "indexed": true }, { "name": "creator_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "title", "type": "VARCHAR(255)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "description", "type": "TEXT", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "starts_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "ends_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": true }, { "name": "max_score", "type": "NUMERIC(8,2)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "status", "type": "VARCHAR(32)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "updated_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "assignment_submission", "description": "Student completion and score for an assignment completed on the platform.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "assignment_id", "type": "UUID", "primary_key": false, "foreign_key": "assignment.id", "nullable": false, "unique": false, "indexed": true }, { "name": "student_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "status", "type": "VARCHAR(32)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "answers", "type": "JSONB", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "score", "type": "NUMERIC(8,2)", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "submitted_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "updated_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "exam_submission", "description": "Student attempt, completion status, and score for an exam taken on the platform.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "exam_id", "type": "UUID", "primary_key": false, "foreign_key": "exam.id", "nullable": false, "unique": false, "indexed": true }, { "name": "student_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "status", "type": "VARCHAR(32)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "answers", "type": "JSONB", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "score", "type": "NUMERIC(8,2)", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "started_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "submitted_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "updated_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "study_session", "description": "Student-managed study schedule entries. Completed sessions contribute study time to performance tracking.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "student_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "course_id", "type": "UUID", "primary_key": false, "foreign_key": "course.id", "nullable": true, "unique": false, "indexed": true }, { "name": "title", "type": "VARCHAR(255)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "starts_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "ends_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "duration_minutes", "type": "INTEGER", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "status", "type": "VARCHAR(32)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "notes", "type": "TEXT", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "updated_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "study_preference", "description": "Student-provided daily or weekly available study hours used by the recommendation engine.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "student_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": true, "indexed": true }, { "name": "period", "type": "VARCHAR(16)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "hours", "type": "NUMERIC(6,2)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "timezone", "type": "VARCHAR(64)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "updated_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "material_summary", "description": "Persisted AI-generated summary of an uploaded material the requesting student is authorized to access. File bytes remain in object storage; embeddings remain in Qdrant.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "material_id", "type": "UUID", "primary_key": false, "foreign_key": "material.id", "nullable": false, "unique": true, "indexed": true }, { "name": "requested_by_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "content", "type": "TEXT", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "model", "type": "VARCHAR(128)", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "quiz", "description": "AI-generated quiz created by a student from authorized uploaded materials.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "student_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "course_id", "type": "UUID", "primary_key": false, "foreign_key": "course.id", "nullable": true, "unique": false, "indexed": true }, { "name": "material_id", "type": "UUID", "primary_key": false, "foreign_key": "material.id", "nullable": true, "unique": false, "indexed": true }, { "name": "title", "type": "VARCHAR(255)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "quiz_question", "description": "Individual question belonging to an AI-generated quiz.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "quiz_id", "type": "UUID", "primary_key": false, "foreign_key": "quiz.id", "nullable": false, "unique": false, "indexed": true }, { "name": "prompt", "type": "TEXT", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "choices", "type": "JSONB", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "correct_option", "type": "VARCHAR(64)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "order_index", "type": "INTEGER", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "quiz_attempt", "description": "Recorded student quiz attempt and score used for performance tracking.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "quiz_id", "type": "UUID", "primary_key": false, "foreign_key": "quiz.id", "nullable": false, "unique": false, "indexed": true }, { "name": "student_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "answers", "type": "JSONB", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "score", "type": "NUMERIC(8,2)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "max_score", "type": "NUMERIC(8,2)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "completed_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true } ] }, { "name": "flashcard_deck", "description": "AI-generated flashcard deck created by a student from authorized uploaded materials.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "student_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "course_id", "type": "UUID", "primary_key": false, "foreign_key": "course.id", "nullable": true, "unique": false, "indexed": true }, { "name": "material_id", "type": "UUID", "primary_key": false, "foreign_key": "material.id", "nullable": true, "unique": false, "indexed": true }, { "name": "title", "type": "VARCHAR(255)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "flashcard", "description": "Single flashcard in a student deck.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "deck_id", "type": "UUID", "primary_key": false, "foreign_key": "flashcard_deck.id", "nullable": false, "unique": false, "indexed": true }, { "name": "front", "type": "TEXT", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "back", "type": "TEXT", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "order_index", "type": "INTEGER", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "flashcard_review", "description": "Per-student flashcard mastery and review history used for performance tracking.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "flashcard_id", "type": "UUID", "primary_key": false, "foreign_key": "flashcard.id", "nullable": false, "unique": false, "indexed": true }, { "name": "student_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "mastery_level", "type": "INTEGER", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "review_count", "type": "INTEGER", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "last_reviewed_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "qa_conversation", "description": "Student RAG Q and A thread. Retrieval is authorized only against that student's private uploads plus official materials of enrolled courses.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "student_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "course_id", "type": "UUID", "primary_key": false, "foreign_key": "course.id", "nullable": true, "unique": false, "indexed": true }, { "name": "title", "type": "VARCHAR(255)", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "updated_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true } ] }, { "name": "qa_message", "description": "User question or assistant answer in a RAG conversation, including the material ids retrieved for grounding.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "conversation_id", "type": "UUID", "primary_key": false, "foreign_key": "qa_conversation.id", "nullable": false, "unique": false, "indexed": true }, { "name": "role", "type": "VARCHAR(16)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "content", "type": "TEXT", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "retrieved_material_ids", "type": "UUID[]", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "study_recommendation", "description": "Explainable study recommendation generated from upcoming deadlines, recorded performance, and available study time.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "student_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "course_id", "type": "UUID", "primary_key": false, "foreign_key": "course.id", "nullable": true, "unique": false, "indexed": true }, { "name": "material_id", "type": "UUID", "primary_key": false, "foreign_key": "material.id", "nullable": true, "unique": false, "indexed": false }, { "name": "assignment_id", "type": "UUID", "primary_key": false, "foreign_key": "assignment.id", "nullable": true, "unique": false, "indexed": false }, { "name": "exam_id", "type": "UUID", "primary_key": false, "foreign_key": "exam.id", "nullable": true, "unique": false, "indexed": false }, { "name": "title", "type": "VARCHAR(255)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "explanation", "type": "TEXT", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "based_on_deadline", "type": "BOOLEAN", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "based_on_performance", "type": "BOOLEAN", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "based_on_study_time", "type": "BOOLEAN", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "priority", "type": "INTEGER", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "suggested_minutes", "type": "INTEGER", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "generated_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true } ] }, { "name": "student_progress", "description": "Per-student per-course progress snapshot combining quiz scores, flashcard mastery, study time, assignment completion, and exam results. Used for dashboards and professor aggregate statistics without exposing private files.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "student_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": false, "unique": false, "indexed": true }, { "name": "course_id", "type": "UUID", "primary_key": false, "foreign_key": "course.id", "nullable": false, "unique": false, "indexed": true }, { "name": "quiz_average", "type": "NUMERIC(5,2)", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "flashcard_mastery_average", "type": "NUMERIC(5,2)", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "study_minutes_total", "type": "INTEGER", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "assignment_completed_count", "type": "INTEGER", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "assignment_total_count", "type": "INTEGER", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "exam_average", "type": "NUMERIC(5,2)", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "exam_completed_count", "type": "INTEGER", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "updated_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false } ] }, { "name": "audit_log", "description": "Audit trail for admin professor verifications, role changes, and denied attempts to access private materials.", "fields": [ { "name": "id", "type": "UUID", "primary_key": true, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "actor_id", "type": "UUID", "primary_key": false, "foreign_key": "user.id", "nullable": true, "unique": false, "indexed": true }, { "name": "action", "type": "VARCHAR(64)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true }, { "name": "target_type", "type": "VARCHAR(64)", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": false }, { "name": "target_id", "type": "UUID", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "detail", "type": "JSONB", "primary_key": false, "foreign_key": null, "nullable": true, "unique": false, "indexed": false }, { "name": "created_at", "type": "TIMESTAMPTZ", "primary_key": false, "foreign_key": null, "nullable": false, "unique": false, "indexed": true } ] } ], "relationships": [ "A user issues zero or more refresh_token rows (user.id -> refresh_token.user_id); a refresh_token may be replaced by a later refresh_token (refresh_token.replaced_by_id -> refresh_token.id).", "A user may submit zero or more professor_verification requests (user.id -> professor_verification.user_id); an admin user may review them (user.id -> professor_verification.reviewed_by_id).", "A user owns zero or more courses (user.id -> course.owner_id): professors own official listed courses with a course_code; students own personal unlisted courses.", "A student enrolls in zero or more official courses (user.id -> enrollment.student_id, course.id -> enrollment.course_id) via search or course code, unique per student and course.", "A course contains zero or more materials (course.id -> material.course_id) uploaded by a user (user.id -> material.uploader_id); visibility private or official isolates student uploads from professors and other students.", "An official course has zero or more announcements authored by a professor (course.id -> announcement.course_id, user.id -> announcement.author_id).", "A course has zero or more assignments and exams created by a user (course.id -> assignment.course_id / exam.course_id, user.id -> assignment.creator_id / exam.creator_id).", "A student submits at most one assignment_submission per assignment and at most one exam_submission per exam (assignment.id / exam.id and user.id as FKs).", "A student schedules zero or more study_session rows optionally focused on a course (user.id -> study_session.student_id, course.id -> study_session.course_id).", "A student has at most one study_preference (user.id -> study_preference.student_id).", "A material has at most one material_summary requested by a student (material.id -> material_summary.material_id, user.id -> material_summary.requested_by_id).", "A student generates zero or more quizzes optionally sourced from a material and course; a quiz has one or more quiz_question rows and zero or more quiz_attempt scores.", "A student generates zero or more flashcard_deck rows; a deck has flashcard rows; each flashcard has at most one flashcard_review per student recording mastery.", "A student starts zero or more qa_conversation threads optionally scoped to a course; each conversation has one or more qa_message rows with retrieved_material_ids for RAG grounding.", "A student receives zero or more study_recommendation rows that may reference a course, material, assignment, or exam and must cite deadline, performance, and/or study-time inputs.", "A student has at most one student_progress snapshot per course, aggregating quiz, flashcard, study-time, assignment, and exam metrics for dashboards and professor aggregates.", "A user may create zero or more audit_log entries (user.id -> audit_log.actor_id) for verification, role change, and private-material access-denied events." ], "indexes": [ "UNIQUE INDEX user_email_key ON user (email) for email/password login and registration uniqueness.", "UNIQUE INDEX user_google_sub_key ON user (google_sub) for Google OAuth account linking.", "INDEX idx_user_role ON user (role) for RBAC lookups.", "PARTIAL INDEX idx_user_professor_verified ON user (professor_verified) WHERE professor_verified = FALSE for admin verification queue.", "UNIQUE INDEX refresh_token_hash_key ON refresh_token (token_hash) for rotating refresh lookup.", "INDEX idx_refresh_token_user_id ON refresh_token (user_id) to revoke all sessions for a user.", "INDEX idx_refresh_token_expires_at ON refresh_token (expires_at) for expiry cleanup.", "PARTIAL UNIQUE INDEX ux_professor_verification_pending ON professor_verification (user_id) WHERE status = 'pending' for one open professor request per user.", "INDEX idx_professor_verification_status ON professor_verification (status) for admin pending list.", "INDEX idx_course_owner_id ON course (owner_id) for professor or student course list.", "INDEX idx_course_visibility_listed ON course (visibility, is_listed) for public official catalog filter.", "UNIQUE INDEX course_code_key ON course (course_code) to enroll by code.", "GIN INDEX idx_course_title_trgm ON course (title gin_trgm_ops) WHERE visibility = 'official' AND is_listed = TRUE for public course search.", "UNIQUE INDEX enrollment_course_student_key ON enrollment (course_id, student_id) to prevent duplicate enrollment.", "INDEX idx_enrollment_student_id ON enrollment (student_id) for student dashboard courses.", "INDEX idx_enrollment_course_id ON enrollment (course_id) for course roster and aggregate stats.", "INDEX idx_material_course_visibility ON material (course_id, visibility) for authorized material lists and RAG ACL scope.", "INDEX idx_material_uploader_id ON material (uploader_id) for owner isolation of private uploads.", "UNIQUE INDEX material_storage_key_key ON material (storage_key) for object-storage key uniqueness.", "INDEX idx_material_ingestion_status ON material (ingestion_status) for ingestion worker retries.", "INDEX idx_announcement_course_published ON announcement (course_id, published_at DESC) for enrolled-student announcement feed.", "PARTIAL INDEX idx_assignment_course_due ON assignment (course_id, due_at) WHERE status = 'published' for upcoming assignments dashboard.", "PARTIAL INDEX idx_exam_course_ends ON exam (course_id, ends_at) WHERE status = 'published' for upcoming exams dashboard.", "UNIQUE INDEX assignment_submission_unique ON assignment_submission (assignment_id, student_id).", "INDEX idx_assignment_submission_student_id ON assignment_submission (student_id) for student completion tracking.", "UNIQUE INDEX exam_submission_unique ON exam_submission (exam_id, student_id).", "INDEX idx_exam_submission_student_id ON exam_submission (student_id).", "INDEX idx_study_session_student_starts ON study_session (student_id, starts_at) for schedule and study-time aggregation.", "UNIQUE INDEX study_preference_student_key ON study_preference (student_id).", "UNIQUE INDEX material_summary_material_key ON material_summary (material_id).", "INDEX idx_quiz_student_id ON quiz (student_id).", "INDEX idx_quiz_attempt_student_completed ON quiz_attempt (student_id, completed_at DESC) for quiz performance history.", "INDEX idx_flashcard_deck_student_id ON flashcard_deck (student_id).", "UNIQUE INDEX flashcard_review_unique ON flashcard_review (flashcard_id, student_id).", "INDEX idx_flashcard_review_student_id ON flashcard_review (student_id) for mastery aggregation.", "INDEX idx_qa_conversation_student_id ON qa_conversation (student_id, updated_at DESC).", "INDEX idx_qa_message_conversation_id ON qa_message (conversation_id, created_at).", "INDEX idx_study_recommendation_student_generated ON study_recommendation (student_id, generated_at DESC).", "UNIQUE INDEX student_progress_unique ON student_progress (student_id, course_id).", "INDEX idx_student_progress_course_id ON student_progress (course_id) for professor aggregate statistics.", "INDEX idx_student_progress_student_id ON student_progress (student_id) for dashboard study progress.", "INDEX idx_audit_log_actor_created ON audit_log (actor_id, created_at DESC).", "INDEX idx_audit_log_action_created ON audit_log (action, created_at DESC)." ], "constraints": [ "user.email is UNIQUE NOT NULL; user.google_sub is UNIQUE when present; at least one of password_hash or google_sub must be set.", "user.role IN ('student', 'professor', 'admin'); role = 'professor' requires professor_verified = TRUE so unverified requesters cannot gain professor permissions.", "professor_verification.status IN ('pending', 'approved', 'rejected'); at most one pending request per user (partial unique index).", "course.visibility IN ('official', 'personal'); official courses MUST have course_code and is_listed = TRUE; personal courses MUST have course_code NULL and is_listed = FALSE.", "course.course_code is UNIQUE (PostgreSQL allows multiple NULLs for personal courses).", "enrollment.method IN ('search', 'course_code'); UNIQUE (course_id, student_id); trigger rejects enrollment into personal courses.", "material.visibility IN ('private', 'official'); trigger requires personal-course materials to be private and official materials to belong only to official courses.", "material.storage_key UNIQUE; byte_size >= 0; ingestion_status IN ('pending', 'processing', 'ready', 'failed'). File bytes are never stored in PostgreSQL.", "announcement trigger allows inserts only for official courses.", "assignment.status and exam.status IN ('draft', 'published'); max_score > 0; exam.ends_at > exam.starts_at when both set.", "assignment_submission UNIQUE (assignment_id, student_id); status IN ('in_progress', 'submitted', 'graded'); score >= 0 when present.", "exam_submission UNIQUE (exam_id, student_id); same status and score checks.", "study_session.ends_at > starts_at; duration_minutes >= 0; status IN ('scheduled', 'completed', 'cancelled').", "study_preference UNIQUE (student_id); period IN ('daily', 'weekly'); hours BETWEEN 0 AND 168.", "material_summary UNIQUE (material_id) so one stored summary is reused per document.", "quiz_question UNIQUE (quiz_id, order_index); flashcard UNIQUE (deck_id, order_index).", "quiz_attempt.score BETWEEN 0 AND max_score; max_score > 0.", "flashcard_review UNIQUE (flashcard_id, student_id); mastery_level BETWEEN 0 AND 5; review_count >= 0.", "qa_message.role IN ('user', 'assistant').", "study_recommendation requires at least one of based_on_deadline, based_on_performance, based_on_study_time; priority >= 0; suggested_minutes >= 0 when set.", "student_progress UNIQUE (student_id, course_id); non-negative counters; assignment_completed_count <= assignment_total_count; quiz/exam averages 0-100; flashcard_mastery_average 0-5.", "Referential actions: course.owner_id ON DELETE RESTRICT; enrollment, submissions, sessions, quizzes, progress CASCADE from parent student or course; material.uploader_id ON DELETE RESTRICT; professor_verification.reviewed_by_id ON DELETE SET NULL; optional course FKs on sessions/quizzes/recommendations ON DELETE SET NULL.", "Embeddings and retrieval indexes are owned by Qdrant, not this schema; object bytes live in S3 referenced by material.storage_bucket and material.storage_key." ], "sql_schema": "CREATE EXTENSION IF NOT EXISTS pgcrypto;\nCREATE EXTENSION IF NOT EXISTS pg_trgm;\n\nCREATE TABLE \"user\" (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n email VARCHAR(255) NOT NULL,\n password_hash VARCHAR(255),\n google_sub VARCHAR(255),\n display_name VARCHAR(255) NOT NULL,\n role VARCHAR(32) NOT NULL DEFAULT 'student',\n professor_verified BOOLEAN NOT NULL DEFAULT FALSE,\n is_active BOOLEAN NOT NULL DEFAULT TRUE,\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT user_email_key UNIQUE (email),\n CONSTRAINT user_google_sub_key UNIQUE (google_sub),\n CONSTRAINT user_role_check CHECK (role IN ('student', 'professor', 'admin')),\n CONSTRAINT user_auth_method_check CHECK (password_hash IS NOT NULL OR google_sub IS NOT NULL),\n CONSTRAINT user_professor_role_check CHECK (\n (role <> 'professor') OR (professor_verified = TRUE)\n )\n);\n\nCREATE TABLE refresh_token (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n user_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE CASCADE,\n token_hash VARCHAR(64) NOT NULL,\n expires_at TIMESTAMPTZ NOT NULL,\n revoked_at TIMESTAMPTZ,\n replaced_by_id UUID REFERENCES refresh_token(id) ON DELETE SET NULL,\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT refresh_token_hash_key UNIQUE (token_hash)\n);\n\nCREATE TABLE professor_verification (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n user_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE CASCADE,\n status VARCHAR(32) NOT NULL DEFAULT 'pending',\n request_note TEXT,\n review_note TEXT,\n reviewed_by_id UUID REFERENCES \"user\"(id) ON DELETE SET NULL,\n reviewed_at TIMESTAMPTZ,\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT professor_verification_status_check CHECK (status IN ('pending', 'approved', 'rejected'))\n);\n\nCREATE TABLE course (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n owner_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE RESTRICT,\n title VARCHAR(255) NOT NULL,\n description TEXT,\n visibility VARCHAR(32) NOT NULL,\n course_code VARCHAR(32),\n is_listed BOOLEAN NOT NULL DEFAULT FALSE,\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT course_visibility_check CHECK (visibility IN ('official', 'personal')),\n CONSTRAINT course_kind_check CHECK (\n (visibility = 'official' AND course_code IS NOT NULL AND is_listed = TRUE)\n OR (visibility = 'personal' AND course_code IS NULL AND is_listed = FALSE)\n ),\n CONSTRAINT course_code_key UNIQUE (course_code)\n);\n\nCREATE TABLE enrollment (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n course_id UUID NOT NULL REFERENCES course(id) ON DELETE CASCADE,\n student_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE CASCADE,\n method VARCHAR(32) NOT NULL,\n enrolled_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT enrollment_course_student_key UNIQUE (course_id, student_id),\n CONSTRAINT enrollment_method_check CHECK (method IN ('search', 'course_code'))\n);\n\nCREATE TABLE material (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n course_id UUID NOT NULL REFERENCES course(id) ON DELETE CASCADE,\n uploader_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE RESTRICT,\n title VARCHAR(255) NOT NULL,\n original_filename VARCHAR(512) NOT NULL,\n content_type VARCHAR(128) NOT NULL,\n storage_bucket VARCHAR(128) NOT NULL,\n storage_key VARCHAR(1024) NOT NULL,\n visibility VARCHAR(32) NOT NULL,\n byte_size BIGINT NOT NULL,\n ingestion_status VARCHAR(32) NOT NULL DEFAULT 'pending',\n ingested_at TIMESTAMPTZ,\n ingestion_error TEXT,\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT material_visibility_check CHECK (visibility IN ('private', 'official')),\n CONSTRAINT material_ingestion_status_check CHECK (ingestion_status IN ('pending', 'processing', 'ready', 'failed')),\n CONSTRAINT material_storage_key_key UNIQUE (storage_key),\n CONSTRAINT material_byte_size_check CHECK (byte_size >= 0)\n);\n\nCREATE TABLE announcement (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n course_id UUID NOT NULL REFERENCES course(id) ON DELETE CASCADE,\n author_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE RESTRICT,\n title VARCHAR(255) NOT NULL,\n body TEXT NOT NULL,\n published_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()\n);\n\nCREATE TABLE assignment (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n course_id UUID NOT NULL REFERENCES course(id) ON DELETE CASCADE,\n creator_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE RESTRICT,\n title VARCHAR(255) NOT NULL,\n description TEXT,\n due_at TIMESTAMPTZ,\n max_score NUMERIC(8,2) NOT NULL DEFAULT 100,\n status VARCHAR(32) NOT NULL DEFAULT 'draft',\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT assignment_status_check CHECK (status IN ('draft', 'published')),\n CONSTRAINT assignment_max_score_check CHECK (max_score > 0)\n);\n\nCREATE TABLE exam (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n course_id UUID NOT NULL REFERENCES course(id) ON DELETE CASCADE,\n creator_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE RESTRICT,\n title VARCHAR(255) NOT NULL,\n description TEXT,\n starts_at TIMESTAMPTZ,\n ends_at TIMESTAMPTZ,\n max_score NUMERIC(8,2) NOT NULL DEFAULT 100,\n status VARCHAR(32) NOT NULL DEFAULT 'draft',\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT exam_status_check CHECK (status IN ('draft', 'published')),\n CONSTRAINT exam_max_score_check CHECK (max_score > 0),\n CONSTRAINT exam_window_check CHECK (starts_at IS NULL OR ends_at IS NULL OR ends_at > starts_at)\n);\n\nCREATE TABLE assignment_submission (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n assignment_id UUID NOT NULL REFERENCES assignment(id) ON DELETE CASCADE,\n student_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE CASCADE,\n status VARCHAR(32) NOT NULL DEFAULT 'in_progress',\n answers JSONB,\n score NUMERIC(8,2),\n submitted_at TIMESTAMPTZ,\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT assignment_submission_unique UNIQUE (assignment_id, student_id),\n CONSTRAINT assignment_submission_status_check CHECK (status IN ('in_progress', 'submitted', 'graded')),\n CONSTRAINT assignment_submission_score_check CHECK (score IS NULL OR score >= 0)\n);\n\nCREATE TABLE exam_submission (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n exam_id UUID NOT NULL REFERENCES exam(id) ON DELETE CASCADE,\n student_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE CASCADE,\n status VARCHAR(32) NOT NULL DEFAULT 'in_progress',\n answers JSONB,\n score NUMERIC(8,2),\n started_at TIMESTAMPTZ,\n submitted_at TIMESTAMPTZ,\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT exam_submission_unique UNIQUE (exam_id, student_id),\n CONSTRAINT exam_submission_status_check CHECK (status IN ('in_progress', 'submitted', 'graded')),\n CONSTRAINT exam_submission_score_check CHECK (score IS NULL OR score >= 0)\n);\n\nCREATE TABLE study_session (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n student_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE CASCADE,\n course_id UUID REFERENCES course(id) ON DELETE SET NULL,\n title VARCHAR(255) NOT NULL,\n starts_at TIMESTAMPTZ NOT NULL,\n ends_at TIMESTAMPTZ NOT NULL,\n duration_minutes INTEGER NOT NULL,\n status VARCHAR(32) NOT NULL DEFAULT 'scheduled',\n notes TEXT,\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT study_session_time_check CHECK (ends_at > starts_at),\n CONSTRAINT study_session_duration_check CHECK (duration_minutes >= 0),\n CONSTRAINT study_session_status_check CHECK (status IN ('scheduled', 'completed', 'cancelled'))\n);\n\nCREATE TABLE study_preference (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n student_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE CASCADE,\n period VARCHAR(16) NOT NULL,\n hours NUMERIC(6,2) NOT NULL,\n timezone VARCHAR(64) NOT NULL DEFAULT 'UTC',\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT study_preference_student_key UNIQUE (student_id),\n CONSTRAINT study_preference_period_check CHECK (period IN ('daily', 'weekly')),\n CONSTRAINT study_preference_hours_check CHECK (hours >= 0 AND hours <= 168)\n);\n\nCREATE TABLE material_summary (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n material_id UUID NOT NULL REFERENCES material(id) ON DELETE CASCADE,\n requested_by_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE CASCADE,\n content TEXT NOT NULL,\n model VARCHAR(128),\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT material_summary_material_key UNIQUE (material_id)\n);\n\nCREATE TABLE quiz (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n student_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE CASCADE,\n course_id UUID REFERENCES course(id) ON DELETE SET NULL,\n material_id UUID REFERENCES material(id) ON DELETE SET NULL,\n title VARCHAR(255) NOT NULL,\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()\n);\n\nCREATE TABLE quiz_question (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n quiz_id UUID NOT NULL REFERENCES quiz(id) ON DELETE CASCADE,\n prompt TEXT NOT NULL,\n choices JSONB NOT NULL,\n correct_option VARCHAR(64) NOT NULL,\n order_index INTEGER NOT NULL,\n CONSTRAINT quiz_question_order_unique UNIQUE (quiz_id, order_index),\n CONSTRAINT quiz_question_order_check CHECK (order_index >= 0)\n);\n\nCREATE TABLE quiz_attempt (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n quiz_id UUID NOT NULL REFERENCES quiz(id) ON DELETE CASCADE,\n student_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE CASCADE,\n answers JSONB NOT NULL,\n score NUMERIC(8,2) NOT NULL,\n max_score NUMERIC(8,2) NOT NULL,\n completed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT quiz_attempt_score_check CHECK (score >= 0 AND max_score > 0 AND score <= max_score)\n);\n\nCREATE TABLE flashcard_deck (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n student_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE CASCADE,\n course_id UUID REFERENCES course(id) ON DELETE SET NULL,\n material_id UUID REFERENCES material(id) ON DELETE SET NULL,\n title VARCHAR(255) NOT NULL,\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()\n);\n\nCREATE TABLE flashcard (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n deck_id UUID NOT NULL REFERENCES flashcard_deck(id) ON DELETE CASCADE,\n front TEXT NOT NULL,\n back TEXT NOT NULL,\n order_index INTEGER NOT NULL,\n CONSTRAINT flashcard_order_unique UNIQUE (deck_id, order_index),\n CONSTRAINT flashcard_order_check CHECK (order_index >= 0)\n);\n\nCREATE TABLE flashcard_review (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n flashcard_id UUID NOT NULL REFERENCES flashcard(id) ON DELETE CASCADE,\n student_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE CASCADE,\n mastery_level INTEGER NOT NULL DEFAULT 0,\n review_count INTEGER NOT NULL DEFAULT 0,\n last_reviewed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT flashcard_review_unique UNIQUE (flashcard_id, student_id),\n CONSTRAINT flashcard_review_mastery_check CHECK (mastery_level >= 0 AND mastery_level <= 5),\n CONSTRAINT flashcard_review_count_check CHECK (review_count >= 0)\n);\n\nCREATE TABLE qa_conversation (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n student_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE CASCADE,\n course_id UUID REFERENCES course(id) ON DELETE SET NULL,\n title VARCHAR(255),\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()\n);\n\nCREATE TABLE qa_message (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n conversation_id UUID NOT NULL REFERENCES qa_conversation(id) ON DELETE CASCADE,\n role VARCHAR(16) NOT NULL,\n content TEXT NOT NULL,\n retrieved_material_ids UUID[] NOT NULL DEFAULT '{}',\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT qa_message_role_check CHECK (role IN ('user', 'assistant'))\n);\n\nCREATE TABLE study_recommendation (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n student_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE CASCADE,\n course_id UUID REFERENCES course(id) ON DELETE SET NULL,\n material_id UUID REFERENCES material(id) ON DELETE SET NULL,\n assignment_id UUID REFERENCES assignment(id) ON DELETE SET NULL,\n exam_id UUID REFERENCES exam(id) ON DELETE SET NULL,\n title VARCHAR(255) NOT NULL,\n explanation TEXT NOT NULL,\n based_on_deadline BOOLEAN NOT NULL DEFAULT FALSE,\n based_on_performance BOOLEAN NOT NULL DEFAULT FALSE,\n based_on_study_time BOOLEAN NOT NULL DEFAULT FALSE,\n priority INTEGER NOT NULL DEFAULT 0,\n suggested_minutes INTEGER,\n generated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT study_recommendation_reason_check CHECK (\n based_on_deadline OR based_on_performance OR based_on_study_time\n ),\n CONSTRAINT study_recommendation_priority_check CHECK (priority >= 0),\n CONSTRAINT study_recommendation_minutes_check CHECK (suggested_minutes IS NULL OR suggested_minutes >= 0)\n);\n\nCREATE TABLE student_progress (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n student_id UUID NOT NULL REFERENCES \"user\"(id) ON DELETE CASCADE,\n course_id UUID NOT NULL REFERENCES course(id) ON DELETE CASCADE,\n quiz_average NUMERIC(5,2),\n flashcard_mastery_average NUMERIC(5,2),\n study_minutes_total INTEGER NOT NULL DEFAULT 0,\n assignment_completed_count INTEGER NOT NULL DEFAULT 0,\n assignment_total_count INTEGER NOT NULL DEFAULT 0,\n exam_average NUMERIC(5,2),\n exam_completed_count INTEGER NOT NULL DEFAULT 0,\n updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n CONSTRAINT student_progress_unique UNIQUE (student_id, course_id),\n CONSTRAINT student_progress_nonneg_check CHECK (\n study_minutes_total >= 0\n AND assignment_completed_count >= 0\n AND assignment_total_count >= 0\n AND exam_completed_count >= 0\n AND assignment_completed_count <= assignment_total_count\n ),\n CONSTRAINT student_progress_quiz_avg_check CHECK (quiz_average IS NULL OR (quiz_average >= 0 AND quiz_average <= 100)),\n CONSTRAINT student_progress_exam_avg_check CHECK (exam_average IS NULL OR (exam_average >= 0 AND exam_average <= 100)),\n CONSTRAINT student_progress_mastery_avg_check CHECK (\n flashcard_mastery_average IS NULL\n OR (flashcard_mastery_average >= 0 AND flashcard_mastery_average <= 5)\n )\n);\n\nCREATE TABLE audit_log (\n id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n actor_id UUID REFERENCES \"user\"(id) ON DELETE SET NULL,\n action VARCHAR(64) NOT NULL,\n target_type VARCHAR(64) NOT NULL,\n target_id UUID,\n detail JSONB,\n created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()\n);\n\nCREATE UNIQUE INDEX ux_professor_verification_pending\n ON professor_verification (user_id)\n WHERE status = 'pending';\n\nCREATE INDEX idx_user_role ON \"user\" (role);\nCREATE INDEX idx_user_professor_verified ON \"user\" (professor_verified) WHERE professor_verified = FALSE;\nCREATE INDEX idx_refresh_token_user_id ON refresh_token (user_id);\nCREATE INDEX idx_refresh_token_expires_at ON refresh_token (expires_at);\nCREATE INDEX idx_professor_verification_status ON professor_verification (status);\nCREATE INDEX idx_professor_verification_user_id ON professor_verification (user_id);\nCREATE INDEX idx_course_owner_id ON course (owner_id);\nCREATE INDEX idx_course_visibility_listed ON course (visibility, is_listed);\nCREATE INDEX idx_course_title_trgm ON course USING GIN (title gin_trgm_ops)\n WHERE visibility = 'official' AND is_listed = TRUE;\nCREATE INDEX idx_enrollment_student_id ON enrollment (student_id);\nCREATE INDEX idx_enrollment_course_id ON enrollment (course_id);\nCREATE INDEX idx_material_course_visibility ON material (course_id, visibility);\nCREATE INDEX idx_material_uploader_id ON material (uploader_id);\nCREATE INDEX idx_material_ingestion_status ON material (ingestion_status);\nCREATE INDEX idx_announcement_course_published ON announcement (course_id, published_at DESC);\nCREATE INDEX idx_assignment_course_due ON assignment (course_id, due_at)\n WHERE status = 'published';\nCREATE INDEX idx_assignment_creator_id ON assignment (creator_id);\nCREATE INDEX idx_exam_course_ends ON exam (course_id, ends_at)\n WHERE status = 'published';\nCREATE INDEX idx_exam_creator_id ON exam (creator_id);\nCREATE INDEX idx_assignment_submission_student_id ON assignment_submission (student_id);\nCREATE INDEX idx_assignment_submission_status ON assignment_submission (assignment_id, status);\nCREATE INDEX idx_exam_submission_student_id ON exam_submission (student_id);\nCREATE INDEX idx_exam_submission_status ON exam_submission (exam_id, status);\nCREATE INDEX idx_study_session_student_starts ON study_session (student_id, starts_at);\nCREATE INDEX idx_study_session_course_id ON study_session (course_id);\nCREATE INDEX idx_material_summary_requested_by_id ON material_summary (requested_by_id);\nCREATE INDEX idx_quiz_student_id ON quiz (student_id);\nCREATE INDEX idx_quiz_material_id ON quiz (material_id);\nCREATE INDEX idx_quiz_attempt_student_completed ON quiz_attempt (student_id, completed_at DESC);\nCREATE INDEX idx_quiz_attempt_quiz_id ON quiz_attempt (quiz_id);\nCREATE INDEX idx_flashcard_deck_student_id ON flashcard_deck (student_id);\nCREATE INDEX idx_flashcard_review_student_id ON flashcard_review (student_id);\nCREATE INDEX idx_qa_conversation_student_id ON qa_conversation (student_id, updated_at DESC);\nCREATE INDEX idx_qa_message_conversation_id ON qa_message (conversation_id, created_at);\nCREATE INDEX idx_study_recommendation_student_generated ON study_recommendation (student_id, generated_at DESC);\nCREATE INDEX idx_student_progress_course_id ON student_progress (course_id);\nCREATE INDEX idx_student_progress_student_id ON student_progress (student_id);\nCREATE INDEX idx_audit_log_actor_created ON audit_log (actor_id, created_at DESC);\nCREATE INDEX idx_audit_log_action_created ON audit_log (action, created_at DESC);\n\nCREATE OR REPLACE FUNCTION prevent_personal_course_enrollment()\nRETURNS TRIGGER AS $$\nBEGIN\n IF EXISTS (\n SELECT 1 FROM course c\n WHERE c.id = NEW.course_id AND c.visibility = 'personal'\n ) THEN\n RAISE EXCEPTION 'enrollments are allowed only on official courses';\n END IF;\n RETURN NEW;\nEND;\n$$ LANGUAGE plpgsql;\n\nCREATE TRIGGER trg_enrollment_official_only\nBEFORE INSERT OR UPDATE OF course_id ON enrollment\nFOR EACH ROW EXECUTE FUNCTION prevent_personal_course_enrollment();\n\nCREATE OR REPLACE FUNCTION enforce_material_visibility()\nRETURNS TRIGGER AS $$\nDECLARE\n course_visibility VARCHAR(32);\nBEGIN\n SELECT c.visibility INTO course_visibility FROM course c WHERE c.id = NEW.course_id;\n IF course_visibility = 'personal' AND NEW.visibility <> 'private' THEN\n RAISE EXCEPTION 'personal course materials must be private';\n END IF;\n IF NEW.visibility = 'official' AND course_visibility <> 'official' THEN\n RAISE EXCEPTION 'official materials can only belong to official courses';\n END IF;\n RETURN NEW;\nEND;\n$$ LANGUAGE plpgsql;\n\nCREATE TRIGGER trg_material_visibility\nBEFORE INSERT OR UPDATE OF course_id, visibility ON material\nFOR EACH ROW EXECUTE FUNCTION enforce_material_visibility();\n\nCREATE OR REPLACE FUNCTION prevent_announcement_on_personal_course()\nRETURNS TRIGGER AS $$\nBEGIN\n IF EXISTS (\n SELECT 1 FROM course c\n WHERE c.id = NEW.course_id AND c.visibility <> 'official'\n ) THEN\n RAISE EXCEPTION 'announcements are allowed only on official courses';\n END IF;\n RETURN NEW;\nEND;\n$$ LANGUAGE plpgsql;\n\nCREATE TRIGGER trg_announcement_official_only\nBEFORE INSERT OR UPDATE OF course_id ON announcement\nFOR EACH ROW EXECUTE FUNCTION prevent_announcement_on_personal_course();", "erd_mermaid": "erDiagram\n user ||--o{ refresh_token : issues\n user ||--o{ professor_verification : requests\n user ||--o{ professor_verification : reviews\n user ||--o{ course : owns\n user ||--o{ enrollment : enrolls\n course ||--o{ enrollment : includes\n course ||--o{ material : contains\n user ||--o{ material : uploads\n course ||--o{ announcement : publishes\n user ||--o{ announcement : authors\n course ||--o{ assignment : contains\n user ||--o{ assignment : creates\n course ||--o{ exam : contains\n user ||--o{ exam : creates\n assignment ||--o{ assignment_submission : receives\n user ||--o{ assignment_submission : submits\n exam ||--o{ exam_submission : receives\n user ||--o{ exam_submission : submits\n user ||--o{ study_session : schedules\n course ||--o{ study_session : focuses\n user ||--|| study_preference : sets\n material ||--o| material_summary : summarized_as\n user ||--o{ material_summary : requests\n user ||--o{ quiz : generates\n course ||--o{ quiz : scopes\n material ||--o{ quiz : sources\n quiz ||--|{ quiz_question : contains\n quiz ||--o{ quiz_attempt : records\n user ||--o{ quiz_attempt : takes\n user ||--o{ flashcard_deck : generates\n course ||--o{ flashcard_deck : scopes\n material ||--o{ flashcard_deck : sources\n flashcard_deck ||--|{ flashcard : contains\n flashcard ||--o{ flashcard_review : reviewed_in\n user ||--o{ flashcard_review : reviews\n user ||--o{ qa_conversation : starts\n course ||--o{ qa_conversation : scopes\n qa_conversation ||--|{ qa_message : contains\n user ||--o{ study_recommendation : receives\n course ||--o{ study_recommendation : targets\n material ||--o{ study_recommendation : suggests\n assignment ||--o{ study_recommendation : deadlines\n exam ||--o{ study_recommendation : deadlines\n user ||--o{ student_progress : tracks\n course ||--o{ student_progress : aggregates\n user ||--o{ audit_log : performs\n user {\n uuid id PK\n varchar email UK\n varchar password_hash\n varchar google_sub UK\n varchar display_name\n varchar role\n boolean professor_verified\n boolean is_active\n timestamptz created_at\n timestamptz updated_at\n }\n refresh_token {\n uuid id PK\n uuid user_id FK\n varchar token_hash UK\n timestamptz expires_at\n timestamptz revoked_at\n uuid replaced_by_id FK\n timestamptz created_at\n }\n professor_verification {\n uuid id PK\n uuid user_id FK\n varchar status\n text request_note\n text review_note\n uuid reviewed_by_id FK\n timestamptz reviewed_at\n timestamptz created_at\n timestamptz updated_at\n }\n course {\n uuid id PK\n uuid owner_id FK\n varchar title\n text description\n varchar visibility\n varchar course_code UK\n boolean is_listed\n timestamptz created_at\n timestamptz updated_at\n }\n enrollment {\n uuid id PK\n uuid course_id FK\n uuid student_id FK\n varchar method\n timestamptz enrolled_at\n }\n material {\n uuid id PK\n uuid course_id FK\n uuid uploader_id FK\n varchar title\n varchar original_filename\n varchar content_type\n varchar storage_bucket\n varchar storage_key UK\n varchar visibility\n bigint byte_size\n varchar ingestion_status\n timestamptz ingested_at\n text ingestion_error\n timestamptz created_at\n timestamptz updated_at\n }\n announcement {\n uuid id PK\n uuid course_id FK\n uuid author_id FK\n varchar title\n text body\n timestamptz published_at\n timestamptz created_at\n timestamptz updated_at\n }\n assignment {\n uuid id PK\n uuid course_id FK\n uuid creator_id FK\n varchar title\n text description\n timestamptz due_at\n numeric max_score\n varchar status\n timestamptz created_at\n timestamptz updated_at\n }\n exam {\n uuid id PK\n uuid course_id FK\n uuid creator_id FK\n varchar title\n text description\n timestamptz starts_at\n timestamptz ends_at\n numeric max_score\n varchar status\n timestamptz created_at\n timestamptz updated_at\n }\n assignment_submission {\n uuid id PK\n uuid assignment_id FK\n uuid student_id FK\n varchar status\n jsonb answers\n numeric score\n timestamptz submitted_at\n timestamptz created_at\n timestamptz updated_at\n }\n exam_submission {\n uuid id PK\n uuid exam_id FK\n uuid student_id FK\n varchar status\n jsonb answers\n numeric score\n timestamptz started_at\n timestamptz submitted_at\n timestamptz created_at\n timestamptz updated_at\n }\n study_session {\n uuid id PK\n uuid student_id FK\n uuid course_id FK\n varchar title\n timestamptz starts_at\n timestamptz ends_at\n integer duration_minutes\n varchar status\n text notes\n timestamptz created_at\n timestamptz updated_at\n }\n study_preference {\n uuid id PK\n uuid student_id FK\n varchar period\n numeric hours\n varchar timezone\n timestamptz created_at\n timestamptz updated_at\n }\n material_summary {\n uuid id PK\n uuid material_id FK\n uuid requested_by_id FK\n text content\n varchar model\n timestamptz created_at\n }\n quiz {\n uuid id PK\n uuid student_id FK\n uuid course_id FK\n uuid material_id FK\n varchar title\n timestamptz created_at\n }\n quiz_question {\n uuid id PK\n uuid quiz_id FK\n text prompt\n jsonb choices\n varchar correct_option\n integer order_index\n }\n quiz_attempt {\n uuid id PK\n uuid quiz_id FK\n uuid student_id FK\n jsonb answers\n numeric score\n numeric max_score\n timestamptz completed_at\n }\n flashcard_deck {\n uuid id PK\n uuid student_id FK\n uuid course_id FK\n uuid material_id FK\n varchar title\n timestamptz created_at\n }\n flashcard {\n uuid id PK\n uuid deck_id FK\n text front\n text back\n integer order_index\n }\n flashcard_review {\n uuid id PK\n uuid flashcard_id FK\n uuid student_id FK\n integer mastery_level\n integer review_count\n timestamptz last_reviewed_at\n }\n qa_conversation {\n uuid id PK\n uuid student_id FK\n uuid course_id FK\n varchar title\n timestamptz created_at\n timestamptz updated_at\n }\n qa_message {\n uuid id PK\n uuid conversation_id FK\n varchar role\n text content\n uuid_array retrieved_material_ids\n timestamptz created_at\n }\n study_recommendation {\n uuid id PK\n uuid student_id FK\n uuid course_id FK\n uuid material_id FK\n uuid assignment_id FK\n uuid exam_id FK\n varchar title\n text explanation\n boolean based_on_deadline\n boolean based_on_performance\n boolean based_on_study_time\n integer priority\n integer suggested_minutes\n timestamptz generated_at\n }\n student_progress {\n uuid id PK\n uuid student_id FK\n uuid course_id FK\n numeric quiz_average\n numeric flashcard_mastery_average\n integer study_minutes_total\n integer assignment_completed_count\n integer assignment_total_count\n numeric exam_average\n integer exam_completed_count\n timestamptz updated_at\n }\n audit_log {\n uuid id PK\n uuid actor_id FK\n varchar action\n varchar target_type\n uuid target_id\n jsonb detail\n timestamptz created_at\n }" }, "api": null, "devops": null, "review": null, "status": "needs_attention", "transcript": [ { "role": "user", "message": "want to build a platform called StudyFlow, an AI-powered university study management platform.Students can create an account, add their university courses, upload lecture notes and PDFs, and organize their study schedule. The platform uses AI to summarize uploaded materials, generate quizzes and flashcards, and answer questions based on the student's uploaded content.Students should have a personalized dashboard showing their courses, upcoming exams, assignments, and study progress. The system should recommend what they should study based on upcoming deadlines, previous performance, and available study time.Professors should be able to create courses, upload materials, publish announcements, and view general student performance statistics.The platform should support authentication with email/password and Google login. Students and professors have different permissions.The system should use a relational database for users, courses, enrollments, assignments, exams, study sessions, and progress. Uploaded documents should be stored separately, and an AI/RAG system should retrieve relevant content when answering questions.I want the application to be a web platform with a React frontend and Python/FastAPI backend. The AI services should be separated from the main backend so they can scale independently.The system should be containerized with Docker and have a CI/CD pipeline. It should be designed to support thousands of concurrent students and should include logging, monitoring, secure authentication, rate limiting, and database backups.", "timestamp": "2026-08-18T19:06:26.678011" }, { "role": "agent", "message": "StudyFlow is an AI-powered university web platform where students manage courses, uploads, schedules, and study progress, and get summaries, quizzes, flashcards, RAG Q&A, and study recommendations. Professors create courses, share materials, publish announcements, and view aggregate performance, with email/password plus Google auth and distinct student vs professor permissions. The intended stack is React, FastAPI, a relational database, separate document storage and AI/RAG services, Docker, and CI/CD, designed for thousands of concurrent students.\nWhen a student adds a course, should they enroll in a professor-created course (shared materials, announcements, and performance stats), create a personal course only they see, or both?\nShould anyone be able to sign up as a student or professor, or is this for a specific university with verified faculty and official courses? And should a professor see only aggregate stats, or also the materials a student uploaded for that course?", "timestamp": "2026-08-18T19:07:29.119397" }, { "role": "user", "message": "Both. Students can enroll in professor-created courses, and they can also create personal courses for private study. Anyone can register as a student, but professors need verification. Professors should only see aggregate performance statistics and official course materials, not private materials uploaded by individual students.", "timestamp": "2026-08-18T19:09:11.508075" }, { "role": "agent", "message": "StudyFlow is a React/FastAPI web platform where students manage courses, uploads, schedules, and AI study tools, and professors run official courses with materials, announcements, and aggregate stats. Students may both enroll in professor-created courses and create private personal courses; anyone can sign up as a student, professors need verification, and professors must not see private student uploads. The remaining gaps are how professors are verified, how students join official courses, and what counts as performance for recommendations and professor statistics.\nHow should professor accounts be verified before they get professor permissions (for example: manual admin approval, university email domain, or an invite code), and who performs that verification?\nHow should a student join a professor-created course (course code, invite link, or public search), and who creates assignments and exams in official versus personal courses?\nWhat should count as student performance for study recommendations and professor statistics (quiz scores, flashcard mastery, study time, assignment completion, or something else)?", "timestamp": "2026-08-18T19:10:18.968281" }, { "role": "user", "message": "Professors are verified manually by an admin. Students join official courses through public search or a course code. Professors create assignments and exams in official courses, while students can create their own assignments and exams in personal courses. Performance includes quiz scores, flashcard mastery, study time, assignment completion, and exam results.", "timestamp": "2026-08-18T19:12:59.018732" }, { "role": "agent", "message": "StudyFlow is a React/FastAPI web platform where students organize courses, materials, schedules, and AI study tools, and professors run official courses with materials, announcements, and aggregate performance stats. Students can enroll in official courses via public search or a course code and also create private personal courses; professors get access only after manual admin verification and cannot see private student uploads. Assignments and exams are created by professors in official courses and by students in personal ones, and performance for recommendations and professor statistics includes quiz scores, flashcard mastery, study time, assignment completion, and exam results.", "timestamp": "2026-08-18T19:14:02.654364" } ], "updated_at": "2026-08-18T19:17:39.198270" }