@@ -7,6 +7,195 @@ Sapling is an AI-powered study companion. It has two services:
77- ** Frontend** — Next.js (TypeScript), lives in ` frontend/ `
88- ** Backend** — FastAPI (Python), lives in ` backend/ `
99
10+ ## Directory Structure
11+
12+ ```
13+ sapling/
14+ ├── CLAUDE.md # Claude Code guidelines and project conventions
15+ ├── README.md # Project overview and setup instructions
16+ ├── docker-compose.yml # Orchestrates frontend + backend containers
17+ ├── landingpage.png # Screenshot of the landing page
18+ ├── .impeccable.md # Impeccable design skill configuration
19+ │
20+ ├── backend/
21+ │ ├── main.py # FastAPI app entry point, registers all routers
22+ │ ├── config.py # Loads and validates env vars (Supabase, Gemini, etc.)
23+ │ ├── requirements.txt # Python dependencies
24+ │ ├── Dockerfile # Backend container image definition
25+ │ ├── .dockerignore # Files excluded from the Docker build context
26+ │ ├── .env # Local secrets (not committed)
27+ │ ├── .env.example # Template showing required env vars
28+ │ │
29+ │ ├── db/
30+ │ │ ├── connection.py # Creates and exports the Supabase client
31+ │ │ ├── supabase_schema.sql # Full Supabase table/index schema
32+ │ │ ├── seed.sql # Sample data for local development
33+ │ │ ├── migration_google_auth.sql # Migration adding Google OAuth user fields
34+ │ │ ├── dedup_nodes.py # One-off script to deduplicate knowledge graph nodes
35+ │ │ └── archive/
36+ │ │ ├── init_db.py # Old DB init script (archived, no longer used)
37+ │ │ ├── schema.sql # Old schema before Supabase migration
38+ │ │ └── seed.py # Old Python-based seed script
39+ │ │
40+ │ ├── models/
41+ │ │ └── __init__.py # Pydantic request/response models package init
42+ │ │
43+ │ ├── prompts/
44+ │ │ ├── preamble.txt # System preamble injected into every AI session
45+ │ │ ├── socratic.txt # Prompt for Socratic questioning study mode
46+ │ │ ├── teachback.txt # Prompt for teach-back (explain-it-back) mode
47+ │ │ ├── expository.txt # Prompt for direct expository explanation mode
48+ │ │ ├── quiz_generation.txt # Prompt for generating quiz questions from content
49+ │ │ ├── quiz_context_update.txt # Prompt for updating quiz state after each answer
50+ │ │ ├── study_match.txt # Prompt for matching students into study groups
51+ │ │ ├── syllabus_extraction.txt # Prompt for extracting assignments from a syllabus
52+ │ │ └── shared_context.txt # Prompt fragment injected when shared course context is on
53+ │ │
54+ │ ├── routes/
55+ │ │ ├── auth.py # Google OAuth sign-in and user upsert endpoints
56+ │ │ ├── calendar.py # Endpoints to read and sync assignment calendar events
57+ │ │ ├── careers.py # Endpoints for job listings and application submission
58+ │ │ ├── documents.py # Upload, classify, summarize, and extract from docs
59+ │ │ ├── extract.py # OCR and text extraction pipeline for uploaded files
60+ │ │ ├── feedback.py # Endpoints to submit session and general user feedback
61+ │ │ ├── flashcards.py # CRUD endpoints for user flashcard decks
62+ │ │ ├── graph.py # Endpoints to build and query the knowledge graph
63+ │ │ ├── learn.py # Streaming AI tutoring chat endpoint (SSE)
64+ │ │ ├── quiz.py # Quiz session creation, answering, and scoring endpoints
65+ │ │ ├── social.py # Study room creation, membership, and chat endpoints
66+ │ │ └── study_guide.py # Endpoint to generate a structured study guide from docs
67+ │ │
68+ │ ├── services/
69+ │ │ ├── assignment_dedupe.py # Deduplicates assignments before inserting into DB
70+ │ │ ├── calendar_service.py # Formats and writes assignments as calendar events
71+ │ │ ├── course_context_service.py # Fetches and caches shared course context for a session
72+ │ │ ├── extraction_service.py # Orchestrates OCR → text extraction for uploaded files
73+ │ │ ├── gemini_service.py # Wrapper around the Gemini API (chat, streaming, vision)
74+ │ │ ├── graph_service.py # Builds knowledge graph nodes and edges from content
75+ │ │ ├── matching_service.py # Matches students into compatible study groups via AI
76+ │ │ ├── quiz_context_service.py # Manages per-session quiz state and context window
77+ │ │ └── social_cache_service.py # Caches room membership and presence for social features
78+ │ │
79+ │ └── tests/
80+ │ ├── conftest.py # Shared pytest fixtures (mock Supabase, Gemini, etc.)
81+ │ ├── README.md # Notes on running and writing backend tests
82+ │ ├── test_assignment_dedupe.py # Tests for assignment deduplication logic
83+ │ ├── test_calendar_routes.py # Tests for calendar sync endpoints
84+ │ ├── test_config.py # Tests that config loads env vars correctly
85+ │ ├── test_documents_routes.py # Tests for document upload and processing endpoints
86+ │ ├── test_extraction_service.py # Tests for the OCR extraction pipeline
87+ │ ├── test_gemini_service.py # Tests for Gemini API wrapper behavior
88+ │ ├── test_graph_service.py # Tests for knowledge graph construction
89+ │ ├── test_learn_routes.py # Tests for the streaming tutoring chat endpoint
90+ │ ├── test_ocr_pipeline.py # Tests for end-to-end OCR pipeline
91+ │ ├── test_quiz_routes.py # Tests for quiz session endpoints
92+ │ ├── test_shared_course_context.py # Tests for shared course context injection
93+ │ └── test_supabase.py # Integration tests against Supabase connection
94+ │
95+ └── frontend/
96+ ├── next.config.ts # Next.js build and runtime configuration
97+ ├── tsconfig.json # TypeScript compiler options
98+ ├── tsconfig.tsbuildinfo # TypeScript incremental build cache
99+ ├── package.json # Node dependencies and npm scripts
100+ ├── package-lock.json # Locked dependency tree
101+ ├── jest.config.js # Jest test runner config (module aliases, transforms)
102+ ├── jest.setup.js # Jest global setup (testing-library, env vars)
103+ ├── eslint.config.mjs # ESLint rules for the frontend
104+ ├── postcss.config.mjs # PostCSS config (Tailwind plugin)
105+ ├── Dockerfile # Frontend container image definition
106+ ├── .dockerignore # Files excluded from the Docker build context
107+ ├── .env.local # Local frontend secrets (not committed)
108+ ├── README.md # Frontend-specific setup notes
109+ │
110+ ├── public/
111+ │ ├── sapling-icon.svg # App icon used in favicon and UI
112+ │ └── sapling-word-icon.png # Full wordmark logo for navbar/branding
113+ │
114+ └── src/
115+ ├── app/
116+ │ ├── layout.tsx # Root layout: Navbar, UserContext, global providers
117+ │ ├── page.tsx # Landing/home page
118+ │ ├── error.tsx # Global Next.js error boundary page
119+ │ ├── globals.css # Tailwind base styles and CSS custom properties
120+ │ ├── icon.svg # App icon for Next.js metadata
121+ │ ├── about/page.tsx # About page with mission and team info
122+ │ ├── calendar/page.tsx # Assignment calendar view with due-date timeline
123+ │ ├── dashboard/page.tsx # User dashboard showing docs, assignments, progress
124+ │ ├── flashcards/page.tsx # Flashcard study and deck management page
125+ │ ├── learn/page.tsx # AI tutoring session page (mode select + chat)
126+ │ ├── library/page.tsx # Document library for uploaded course materials
127+ │ ├── privacy/page.tsx # Privacy policy page
128+ │ ├── social/page.tsx # Study rooms and peer matching page
129+ │ ├── terms/page.tsx # Terms of service page
130+ │ ├── tree/page.tsx # Knowledge graph tree visualization page
131+ │ ├── signin/callback/page.tsx # OAuth callback handler that exchanges code for session
132+ │ ├── careers/
133+ │ │ ├── jobs.ts # Static list of open job positions
134+ │ │ ├── page.tsx # Careers listing page
135+ │ │ └── [slug]/
136+ │ │ ├── page.tsx # Individual job detail page
137+ │ │ └── ApplyForm.tsx # Job application form component
138+ │ └── study/
139+ │ ├── page.tsx # Study session entry point (SSR shell)
140+ │ ├── StudyClient.tsx # Client-side study session orchestrator
141+ │ └── FlashcardsPanel.tsx # Inline flashcard panel within a study session
142+ │
143+ ├── components/
144+ │ ├── AIDisclaimerChip.tsx # Small chip shown on AI-generated content
145+ │ ├── AssignmentTable.tsx # Table displaying assignments with status and due dates
146+ │ ├── Avatar.tsx # User avatar with initials fallback
147+ │ ├── ChatPanel.tsx # Main AI chat UI with streaming message rendering
148+ │ ├── CustomSelect.tsx # Styled dropdown select component
149+ │ ├── DisclaimerModal.tsx # Modal shown on first use with AI disclaimer
150+ │ ├── ErrorBoundary.tsx # React error boundary wrapper for safe rendering
151+ │ ├── FeedbackFlow.tsx # Multi-step general feedback submission flow
152+ │ ├── HowItWorks.tsx # Landing page section explaining the product
153+ │ ├── KnowledgeGraph.tsx # D3-powered interactive knowledge graph visualization
154+ │ ├── ModeSelector.tsx # Selector for choosing AI tutoring mode (Socratic, etc.)
155+ │ ├── Navbar.tsx # Top navigation bar with auth state and links
156+ │ ├── OnboardingModal.tsx # First-run onboarding modal for new users
157+ │ ├── QuizPanel.tsx # Quiz UI for answering and reviewing questions
158+ │ ├── ReportIssueFlow.tsx # Flow for users to report bugs or content issues
159+ │ ├── RoomChat.tsx # Real-time chat UI for a study room (Supabase Realtime)
160+ │ ├── RoomList.tsx # List of available and joined study rooms
161+ │ ├── RoomMembers.tsx # Displays current members of a study room
162+ │ ├── RoomOverview.tsx # Overview card for a study room (name, topic, members)
163+ │ ├── SchoolDirectory.tsx # Directory for browsing schools and courses
164+ │ ├── SessionFeedbackFlow.tsx # In-session feedback prompt after study sessions
165+ │ ├── SessionFeedbackGlobal.tsx # Global wrapper that triggers session feedback on navigate
166+ │ ├── SessionSummary.tsx # Post-session summary of topics covered and performance
167+ │ ├── SharedContextToggle.tsx # Toggle to enable/disable shared course context in chat
168+ │ ├── SpaceBackground.tsx # Animated starfield canvas background
169+ │ ├── StudyMatch.tsx # UI for finding and joining study partner matches
170+ │ └── UploadZone.tsx # Drag-and-drop file upload zone for course documents
171+ │
172+ ├── context/
173+ │ └── UserContext.tsx # React context providing authenticated user state globally
174+ │
175+ ├── lib/
176+ │ ├── api.ts # Typed fetch helpers for every backend API endpoint
177+ │ ├── avatarUtils.ts # Utilities for generating avatar initials and colors
178+ │ ├── graphUtils.ts # Helpers for transforming graph data for D3 rendering
179+ │ ├── supabase.ts # Supabase browser client singleton
180+ │ └── types.ts # Shared TypeScript types used across the frontend
181+ │
182+ ├── __mocks__/
183+ │ ├── rehypeKatex.js # Mock for ESM-only rehype-katex (Jest compat)
184+ │ ├── remarkMath.js # Mock for ESM-only remark-math (Jest compat)
185+ │ └── styleMock.js # Mock for CSS/image imports in Jest
186+ │
187+ └── __tests__/
188+ ├── README.md # Notes on frontend test conventions
189+ ├── api.test.ts # Tests for API helper functions
190+ ├── authAndPrefillWiring.test.ts # Tests for auth flow and form pre-fill logic
191+ ├── chatPanel.test.tsx # Tests for ChatPanel rendering and streaming
192+ ├── dataFetching.test.tsx # Tests for data-fetching hooks and loading states
193+ ├── graphUtils.test.ts # Tests for graph transformation utilities
194+ ├── hydration.test.tsx # Tests for SSR/CSR hydration correctness
195+ ├── sessionSummary.test.tsx # Tests for SessionSummary rendering
196+ └── userContext.test.tsx # Tests for UserContext auth state management
197+ ```
198+
10199## Running Locally
11200
12201** Backend**
0 commit comments