A full-stack AI learning platform supporting classroom-based learning and personalised self-study workflows.
C.O.T.E.ai combines retrieval-augmented generation, assessments, flashcards, progress tracking, teacher analytics, and AI-generated learning roadmaps in a React and FastAPI application powered by AWS Bedrock.
Deployment status: The application was deployed on AWS EC2 during the hackathon. The Elastic IP and paid cloud infrastructure were later decommissioned to avoid recurring charges, so a live public deployment is not currently maintained.
The platform provides two learning tracks:
Designed for teachers and students working within classrooms.
- Teacher and student authentication
- Classroom creation and enrolment codes
- Student classroom joining
- PDF learning-material uploads
- Background document ingestion
- RAG-based doubt resolution grounded in uploaded material
- Topic-wise flashcard generation
- Three-level assessments
- XP, mistakes, progress, and remedial workflows
- Teacher assessment previews and analytics
- Teacher-review ingestion for improving future responses
Designed for independent learners.
- AI-generated personalised roadmaps
- Week-by-week and day-by-day learning structure
- Detailed content for the initial week
- On-demand generation of later weeks
- Daily completion and progress tracking
- Coding-practice and learning-resource recommendations
- Interview-preparation content for relevant technical roadmaps
This project was developed as a team project. My primary contributions were:
- Implemented the shared AWS Bedrock inference utility using the Bedrock Converse API.
- Migrated four AI workflows—RAG retrieval, flashcards, assessments, and personalised roadmaps—from Google/Gemini integrations to AWS Bedrock.
- Added configurable model and AWS-region handling through environment variables.
- Implemented text and multimodal Bedrock invocation for processing textual and visual document content.
- Integrated multimodal document summarisation into the ingestion pipeline.
- Led deployment and integration of the React and FastAPI application on AWS EC2 during the hackathon.
- Added 26 offline tests for Bedrock request construction, response parsing, multimodal handling, and service migration.
- Added full-stack continuous integration for backend syntax validation, offline testing, dependency auditing, and frontend production builds.
Uploaded classroom documents are:
- Parsed and divided into chunks
- Converted into HuggingFace embeddings
- Stored in ChromaDB
- Retrieved according to the student's query
- Supplied as grounded context to AWS Bedrock
Institution-track responses can be restricted to material uploaded for the selected classroom.
The system generates revision flashcards from classroom material and supports:
- Topic-wise card generation
- Multiple languages
- Cached results
- Manual editing
- AI-assisted card refinement
The assessment flow includes:
- Three progressive difficulty levels
- AI-generated questions
- Assessment submission and scoring
- XP and unlock progression
- Mistake tracking
- Teacher previews
- Remedial learning workflows
Individual learners can generate roadmaps based on:
- Learning objective
- Requested duration
- Skill or technical domain
- Daily learning tasks
- Practice and learning resources
The first week receives detailed content initially, while later weeks can be generated on demand.
Teachers can:
- Create classrooms
- Share enrolment codes
- Upload or remove learning material
- View enrolled students
- Preview assessments
- Review student progress and analytics
Students can:
- Join classrooms
- Access uploaded material
- Ask grounded questions
- Generate flashcards
- Complete assessments
- Review mistakes and progress
┌──────────────────────────┐
│ React + TypeScript UI │
│ Vite / Tailwind / MUI │
└─────────────┬────────────┘
│ REST APIs
┌─────────────▼────────────┐
│ FastAPI Backend │
│ Auth / Classrooms / APIs │
└───────┬─────────┬────────┘
│ │
┌────────────────┘ └─────────────────┐
│ │
┌─────────▼──────────┐ ┌─────────▼──────────┐
│ AI Services │ │ Persistence │
│ │ │ │
│ Retrieval │ │ SQLite metadata │
│ Flashcards │ │ JSON auth/progress │
│ Assessments │ │ Local uploads │
│ Roadmaps │ │ Optional S3 backup │
└─────────┬──────────┘ └────────────────────┘
│
┌─────────▼──────────┐
│ bedrock_utils.py │
│ Shared Converse API│
└─────────┬──────────┘
│
┌─────────▼──────────┐
│ AWS Bedrock │
│ Text + Multimodal │
└────────────────────┘
PDF ingestion ──► parsing/OCR ──► chunking
──► HuggingFace embeddings ──► ChromaDB
- React 18
- TypeScript
- Vite
- Tailwind CSS
- Material UI
- Radix UI
- Framer Motion
- Python
- FastAPI
- Pydantic
- SQLite
- JSON-based session and progress persistence
- AWS Bedrock
- Bedrock Converse API
- LangChain
- ChromaDB
- HuggingFace sentence-transformer embeddings
- Text and multimodal model invocation
- Unstructured
- Poppler
- Tesseract OCR
- PDF text and visual-content processing
- Pytest
- GitHub Actions
- npm dependency auditing
- Vite production-build validation
AWS-hackathon/
│
├── .github/
│ └── workflows/
│ └── ci.yml
│
├── frontend/ # React and TypeScript frontend
│
├── tests/
│ ├── conftest.py
│ ├── test_bedrock_migration.py
│ └── test_bedrock_utils.py
│
├── bedrock_utils.py # Shared Bedrock inference abstraction
├── retrieval_service.py # RAG retrieval and answer generation
├── flashcard_service.py # Flashcard generation and editing
├── assessment_service.py # Assessments, XP and mistakes
├── roadmap_service.py # Roadmap generation and progress
├── ingestion_pipeline.py # PDF ingestion and vector indexing
├── topic_mapper.py # Topic grouping utilities
├── main.py # FastAPI routes and application wiring
├── requirements.txt # Full backend dependencies
├── requirements-dev.txt # Lightweight offline-test dependencies
├── Dockerfile # Optional container configuration
└── README.md
The Dockerfile remains available as an optional container configuration. The hackathon deployment described in this README used AWS EC2 rather than Docker-based hosting.
The shared bedrock_utils.py module provides:
- Configurable AWS region
- Configurable Bedrock model ID
- Message normalisation
- Text inference
- Multimodal inference
- Image-format detection
- Converse API request construction
- Text-response extraction
The following services use the shared abstraction:
retrieval_service.pyflashcard_service.pyassessment_service.pyroadmap_service.py
This centralises model configuration and avoids duplicating Bedrock invocation logic across individual features.
Create a .env file in the project root.
AWS_REGION=us-east-1
BEDROCK_MODEL_ID=amazon.nova-2-lite-v1:0
# Allowed frontend origins
CORS_ORIGINS=http://localhost:5173
# Optional S3 backup for uploaded material
S3_BUCKET_NAME=AWS credentials should be provided through the standard AWS credential chain, such as:
- A configured AWS CLI profile
- Environment-based credentials
- An IAM role when running on AWS infrastructure
Do not commit AWS credentials or access keys.
The configured AWS account must have access to the selected Bedrock model.
- Python 3.11 recommended
- Node.js 20 or later
- npm
- AWS credentials with Bedrock access
- Poppler and Tesseract for complete PDF/OCR support
Create a virtual environment:
python -m venv .venv
.\.venv\Scripts\Activate.ps1python3 -m venv .venv
source .venv/bin/activateInstall the full application dependencies:
python -m pip install -r requirements.txtStart FastAPI:
uvicorn main:app --reloadThe backend will normally be available at:
http://localhost:8000
OpenAPI documentation:
http://localhost:8000/docs
cd frontend
npm ci
npm run devThe frontend will normally be available at:
http://localhost:5173
Optional frontend/.env:
VITE_API_BASE_URL=http://localhost:8000The offline tests require no AWS credentials and make no live Bedrock calls.
Create or activate a virtual environment, then install the lightweight test dependencies:
python -m pip install -r requirements-dev.txtRun all backend tests:
python -m pytest -v testsCurrent validated result:
26 passed
The tests cover:
- Plain-text and structured-message normalisation
- Image-format detection
- Bedrock Converse request construction
- Text-response extraction
- Empty-response handling
- Multimodal image decoding
- Bedrock exception propagation
- Retrieval-service Bedrock migration
- Flashcard-service Bedrock migration
- Assessment-service Bedrock migration
- Roadmap-service Bedrock migration
- Removal of legacy Google Generative AI imports
Install the locked dependency tree:
npm --prefix frontend ciAudit dependencies:
npm --prefix frontend auditBuild the production frontend:
npm --prefix frontend run buildCurrent validation:
0 npm vulnerabilities
Production build successful
The Full-stack CI workflow runs two independent jobs.
- Sets up Python
- Installs lightweight test dependencies
- Compiles important backend modules
- Runs all 26 offline tests
- Sets up Node.js
- Installs locked dependencies
- Audits the dependency tree
- Builds the Vite production application
The tests do not use live AWS credentials and therefore do not incur Bedrock charges.
GET /
GET /health
POST /api/auth/signup
POST /api/auth/login
GET /api/auth/me
POST /api/auth/logout
POST /upload
POST /ask
GET /api/classrooms/mine
POST /api/classrooms
POST /api/classrooms/join
GET /api/classrooms/{classroom_id}/people
DELETE /api/classrooms/{classroom_id}/materials/{material_id}
GET /api/flashcards/{session_id}
POST /api/flashcards/update
POST /api/flashcards/ai-edit
POST /api/assessment/generate
POST /api/assessment/submit
GET /api/mistakes/{session_id}
POST /api/mistakes/comment
GET /api/progress/{session_id}
POST /api/add_xp
POST /api/spend_xp
POST /api/remedial/complete
POST /api/roadmap/generate
GET /api/roadmaps/{session_id}
GET /api/roadmap/{roadmap_id}
POST /api/roadmap/{roadmap_id}/complete_day
POST /api/roadmap/{roadmap_id}/generate_week
During the hackathon, the integrated application was deployed on AWS EC2.
The deployment work included:
- Configuring the EC2 environment
- Connecting the React frontend and FastAPI backend
- Configuring AWS region and Bedrock model access
- Updating frontend/backend service URLs
- Validating the deployed application
- Associating an Elastic IP for public access
After the hackathon, the Elastic IP and paid hosting infrastructure were removed to prevent recurring charges.
The absence of a current live URL therefore does not indicate that the application was never deployed.
This repository represents a hackathon prototype rather than a production learning-management system.
Current limitations include:
- No active public deployment
- No live AWS integration test in CI
- Bedrock behaviour depends on external model availability
- Model calls are synchronous
- SQLite and JSON persistence are not designed for distributed deployment
- Authentication and secret management require production hardening
- PDF ingestion requires large local dependencies
- Generated content requires appropriate user review
- Monitoring, tracing, and structured production logging are limited
- The offline tests validate integration logic but not the quality of live model output
- Add mocked service-level tests for flashcard and roadmap JSON repair
- Add API integration tests using a temporary test database
- Add deployment-as-code using AWS CDK or Terraform
- Add production secret management
- Add asynchronous model execution
- Add structured logging and observability
- Replace local JSON persistence with a managed database
- Add caching and queue-based background processing
- Add evaluation datasets for retrieval quality
- Measure groundedness, precision, and answer relevance
- Add frontend code splitting to reduce initial bundle size
- Add a human-review workflow for generated assessments and roadmaps
C.O.T.E.ai is an educational hackathon prototype.
It is not currently maintained as a production service, and AI-generated learning content should be reviewed before academic or institutional use.