Project Guide | Beaver Study Orchestrator

Live Demo

Open the public GitHub Pages demo
Scope: credential-free, synthetic-data demo for students, advisors, and technical evaluators.

Product proof surface This repository leads with the working study-planning product: parser, scheduler, risk model, what-if analysis, history, and calendar export. Commercial exploration is limited to the private inquiry lane listed in the service manifest.

A study-planning tool that extracts deadlines from syllabus text, generates adaptive schedules, and provides interpretable risk scoring with what-if simulation.

System Overview

A study planner that turns syllabus data into schedules, risk signals, and what-if decisions students can act on.

Area	Details
Users	Students, advisors, bootcamps, education platforms, and productivity-tool evaluators.
Technical path	Validate the demo, README, architecture notes, and quality gate before deeper workflow review.
System scope	Syllabus extraction, adaptive scheduling, risk scoring, what-if simulation, FastAPI/NLP planning surface.
Operating boundary	Study guidance is advisory; personal education data needs explicit retention and sharing controls.
Evaluation path	Run the planner tests and inspect sample schedules, risk outputs, and scenario simulations.

Evaluation Path

Start here: Run one syllabus through analyze, then compare the risk drivers with the what-if result.
Local demo: Run make setup && make run, then open http://127.0.0.1:8000.
Checks: Run make test; CI also enforces lint and coverage on supported Python versions.

Architecture Notes

Architecture guide summarizes the system scope, first files to inspect, runtime commands, and known boundaries.
Quality notes lists the local checks, CI surface, and release expectations for this repository.
Enterprise readiness notes outlines security, data, operations, integration, and handoff expectations.
Repository positioning records scope boundaries and current technical entry points.

What it does

Syllabus extraction - Parses due dates from free-form text, detects task types (assignment, exam, project, etc.), estimates effort with rule-based heuristics
Schedule generation - Builds date-by-date study allocations based on weekday availability, avoids single-day cramming
Risk analytics - Risk score (0.0-1.0) with top drivers (coverage gap, urgency, workload), mitigation recommendations
What-if simulation - See how risk changes when you add extra study hours per day
Calendar export - Exports study sessions as .ics for Google Calendar / Apple Calendar
Diagnostics - Busiest day, deadline buffer, total focus days, recovery hours needed

Quickstart

make setup
make run

Open http://127.0.0.1:8000. Requires Python 3.11+; if your default python3 is older, run make BOOTSTRAP_PYTHON=/path/to/python3.11 verify.

How it works

[Browser UI]
   |  POST /api/analyze, POST /api/what-if
   v
[FastAPI app.main]
   |-- syllabus_parser.py   (text -> tasks)
   |-- scheduler.py         (tasks + availability -> daily plan)
   |-- risk_model.py        (tasks + plan -> risk + mitigation)
   +-- calendar_export.py   (plan -> .ics)

API

Endpoint	Description
`GET /api/health`	Parser status and export readiness
`POST /api/analyze`	Analyze syllabus text
`POST /api/what-if`	Simulate schedule with different availability
`GET /api/export/ics`	Export study plan as .ics calendar
`GET /api/outcomes/board`	Risk and what-if summary dashboard
`GET /api/schema/analysis-report`	Analysis payload schema

Tech Stack

Backend: FastAPI, Pydantic
Frontend: Vanilla JS + HTML/CSS
Testing: Pytest, FastAPI TestClient
Runtime: Python 3.11+

Tests

Metric	Value
Test count	40
Line coverage	96%
CI threshold	80%
CI matrix	Python 3.11, 3.12
Lint	ruff (zero warnings)

Covers: date parsing (including year-boundary edges), what-if simulation, history persistence, outcome board, risk analytics, scheduler allocation, API contracts, and frontend metadata.

All request bodies are validated with Pydantic v2 (Field constraints + field_validator). Invalid payloads get 422 responses with structured error details.

make test

Design Decisions

Rule-based extraction over LLM calls - deterministic, offline-friendly, no token cost
Interpretable risk model - clear feature effects, easy to explain in technical walkthroughs
Single-page app - fast demo flow, no auth friction

Known Limitations

Date parser handles common English month formats and MM/DD / MM-DD
Effort estimation is heuristic, not personalized
No calendar/LMS sync yet

CI

GitHub Actions runs ruff lint and pytest --cov-fail-under=80 on every push/PR across Python 3.11 and 3.12.

Cloud + AI Architecture

Cloud + AI architecture blueprint
Machine-readable architecture manifest
Validation command: python3 scripts/validate_architecture_blueprint.py

Enterprise Productization

Product operating model defines the product scope, trust boundary, operating checks, and service path for this repository.

System Architecture

System architecture maps the runtime boundary, data/control flow, cloud or local deployment surface, and operating assumptions for this repository.

Service Architecture

Service architecture defines the cloud resources, account information, cost controls, and production guardrails needed to turn this repo into a scoped service without publishing public financial assumptions.

Search And Service Surface

Public entry: free local study planner and public demo
Paid boundary: Consumer Prototype Customization
Canonical URL: https://beaver-study-orchestrator.pages.dev/
Lead capture: https://kim3310-doeon-kim-portfolio.pages.dev/?offer=beaver-study-orchestrator&inquiry=consumer-prototype-customization#private-inquiry
Resource route: https://kim3310-doeon-kim-portfolio.pages.dev/resources/beaver-study-orchestrator/
Commercial route: https://kim3310-doeon-kim-portfolio.pages.dev/?offer=beaver-study-orchestrator#service-offers
Machine-readable offer: docs/service-offer.json
Search growth implementation: docs/search-growth-implementation.md
Revenue architecture: docs/revenue-architecture.md