AIVO AI Platform

Adaptive learning platform for students with special needs

🏗️ Architecture

This is a monorepo managed with pnpm workspaces and Turborepo for efficient build caching and task execution## 📚 Documentation

Project Documentation

• Quick Start Guide - Get started quickly
• Project Structure - Architecture overview
• TypeScript Configuration - Complete TypeScript setup guide
• TypeScript Summary - Quick reference

Infrastructure & DevOps

• Terraform Infrastructure - AWS infrastructure documentation
• Terraform Setup Guide - Step-by-step deployment
• CI/CD Pipeline - Complete CI/CD documentation
• CI/CD Quick Reference - Quick reference guide
• Secrets Setup - GitHub secrets configuration

External Documentation

• Turborepo Documentation
• pnpm Workspaces
• FastAPI Documentation
• React Documentation
• TypeScript Handbook## Structure

aivo-ai-platform/
├── apps/
│   ├── webapp-iep/          # IEP Management Web Application (Phase 1)
│   └── webapp-learner/      # Student Learning Web Application (Phase 2)
├── services/
│   ├── api-gateway/         # FastAPI Gateway Service
│   └── auth-service/        # Authentication Microservice
├── packages/
│   ├── ui/                  # Shared React Component Library
│   └── types/               # Shared TypeScript Types
└── infra/
    └── terraform/           # Infrastructure as Code

📋 Prerequisites

• Node.js >= 18.0.0
• pnpm >= 10.0.0 (specifically pnpm@10.18.2)
• Python >= 3.11 (for backend services)
• PostgreSQL >= 14.0 (primary database)
• Redis >= 7.0 (caching and sessions)
• Terraform >= 1.0.0 (for infrastructure)

🚀 Getting Started

1. Install pnpm (if not already installed)

# Using npm
npm install -g pnpm

# Or using PowerShell (Windows)
iwr https://get.pnpm.io/install.ps1 -useb | iex

2. Clone and Install Dependencies

# Clone the repository
git clone <repository-url>
cd aivo-ai-platform

# Install all dependencies across workspaces
pnpm install

3. Development

# Run all apps and services in development mode
pnpm dev

# Run a specific workspace
pnpm --filter @aivo/webapp-iep dev

# Run multiple specific workspaces
pnpm --filter @aivo/webapp-iep --filter @aivo/api-gateway dev

🔧 Available Commands

Root Level Commands

Command	Description
pnpm dev	Start all apps in development mode
pnpm build	Build all packages and apps
pnpm test	Run tests across all workspaces
pnpm lint	Lint all workspaces
pnpm format	Format code with Prettier
pnpm type-check	TypeScript type checking
pnpm clean	Clean all build outputs and node_modules

Workspace-Specific Commands

# Format: pnpm --filter <workspace-name> <command>

# Examples:
pnpm --filter @aivo/webapp-iep build
pnpm --filter @aivo/ui dev
pnpm --filter @aivo/types build

📦 Workspaces

Apps

@aivo/webapp-iep

React web application for IEP (Individualized Education Program) management. Built with:

• React 18
• TypeScript
• Vite

@aivo/webapp-learner (Phase 2)

Student-facing learning application. Built with:

• React 18
• TypeScript
• Vite

Services

@aivo/api-gateway

FastAPI-based API gateway service

• Port: 8000
• Python 3.11+
• FastAPI

@aivo/auth-service

Authentication and authorization microservice

• Port: 8001
• Python 3.11+
• FastAPI

Packages

@aivo/ui

Shared React component library for consistent UI across applications.

@aivo/types

Shared TypeScript type definitions for type safety across the monorepo.

� Dependencies Overview

Root Package Dependencies

Development Tools:

• @turbo/gen 2.5.8 - Workspace code generation
• turbo 2.5.8 - Build system orchestration
• prettier 3.6.2 - Code formatting
• typescript 5.9.3 - TypeScript compiler

Testing:

• vitest 3.2.4 - Unit testing framework
• @vitest/ui 3.2.4 - Test UI dashboard
• @testing-library/react 16.3.0 - React testing utilities
• @testing-library/jest-dom 6.9.1 - DOM matchers
• jsdom 27.0.0 - DOM implementation

Linting:

• eslint 9.37.0 - JavaScript/TypeScript linter
• @typescript-eslint/eslint-plugin 8.46.1 - TypeScript rules
• @typescript-eslint/parser 8.46.1 - TypeScript parser
• eslint-plugin-react 7.37.5 - React rules
• eslint-plugin-react-hooks 7.0.0 - React Hooks rules

Backend Dependencies (Python)

Core Framework:

• fastapi 0.104.1 - Modern web framework
• uvicorn[standard] 0.24.0 - ASGI server
• pydantic 2.10.0 - Data validation
• pydantic-settings 2.1.0 - Settings management
• python-dotenv 1.0.0 - Environment variables

Database:

• sqlalchemy[asyncio] 2.0.23 - ORM with async support
• asyncpg 0.29.0 - Async PostgreSQL driver
• psycopg2-binary 2.9.9 - PostgreSQL adapter
• alembic 1.12.1 - Database migrations
• redis 4.6.0 - Redis client

Authentication & Security:

• python-jose[cryptography] 3.3.0 - JWT tokens
• passlib[bcrypt] 1.7.4 - Password hashing
• email-validator 2.1.0 - Email validation
• pyotp 2.9.0 - 2FA/TOTP support

File Handling & Storage:

• python-multipart 0.0.6 - Multipart form data
• boto3 1.34.0 - AWS SDK
• botocore 1.34.0 - AWS core
• clamd 1.0.2 - ClamAV integration
• aiofiles 23.2.1 - Async file operations

AI & Content Generation:

• openai 1.10.0 - OpenAI API client
• textstat 0.7.3 - Text readability analysis

Data Analysis:

• scipy 1.16.2 - Scientific computing
• numpy 2.2.6 - Numerical operations

Task Scheduling:

• apscheduler 3.10.4 - Job scheduling
• celery[redis] 5.3.4 - Distributed task queue

Monitoring & Observability:

• python-json-logger 2.0.7 - Structured logging
• structlog 24.1.0 - Structured logging
• sentry-sdk[fastapi] 1.40.0 - Error tracking
• prometheus-client 0.19.0 - Metrics collection
• opentelemetry-api 1.27.0 - Tracing API
• opentelemetry-sdk 1.27.0 - Tracing SDK
• opentelemetry-instrumentation-fastapi 0.48b0 - FastAPI tracing
• opentelemetry-instrumentation-sqlalchemy 0.48b0 - SQLAlchemy tracing
• opentelemetry-instrumentation-redis 0.48b0 - Redis tracing
• opentelemetry-instrumentation-httpx 0.48b0 - HTTP tracing
• opentelemetry-exporter-otlp 1.27.0 - OTLP exporter

Rate Limiting:

• fastapi-limiter 0.1.6 - Rate limiting for FastAPI
• slowapi 0.1.9 - Rate limiting middleware

HTTP Client:

• httpx 0.25.1 - Async HTTP client

Frontend Dependencies

Core (configured via package manager):

• react 19 - UI library
• typescript 5.9+ - Type system
• axios - HTTP client for API calls
• @tanstack/react-query - Server state management
• @mui/material - Material-UI components
• @mui/icons-material - Material-UI icons
• react-router-dom - Client-side routing

�🔄 Working with Python Services

Python services (api-gateway, auth-service) require separate setup:

# Navigate to service directory
cd services/api-gateway

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows PowerShell:
.\venv\Scripts\Activate.ps1
# Unix/MacOS:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run service
uvicorn main:app --reload --port 8000

Installing Additional Python Dependencies

# Add a new dependency
pip install <package-name>

# Update requirements.txt
pip freeze > requirements.txt

# Or manually add to requirements.txt with version pinning
echo "package-name==1.0.0" >> requirements.txt

🏗️ Building

# Build all workspaces (Turborepo will handle dependencies)
pnpm build

# Build specific workspace
pnpm --filter @aivo/ui build

Turborepo will automatically:

• Build dependencies first (e.g., @aivo/types before @aivo/ui)
• Cache build outputs for faster subsequent builds
• Run builds in parallel where possible

🧪 Testing

# Run all tests
pnpm test

# Run tests for specific workspace
pnpm --filter @aivo/webapp-iep test

📝 Code Quality

# Lint all workspaces
pnpm lint

# Format all code
pnpm format

# Type check all TypeScript code
pnpm type-check

🌳 Adding New Packages

TypeScript/JavaScript Package

# Create directory
mkdir packages/new-package
cd packages/new-package

# Initialize package
pnpm init

# Add to workspace by updating the package.json name
# Name should follow: @aivo/<package-name>

Adding Dependencies

# Add dependency to specific workspace
pnpm --filter @aivo/webapp-iep add react-router-dom

# Add dev dependency
pnpm --filter @aivo/webapp-iep add -D @types/node

# Add workspace dependency
pnpm --filter @aivo/webapp-iep add @aivo/ui --workspace

🔐 Environment Variables

Create .env.local files in each app/service directory:

# apps/webapp-iep/.env.local
VITE_API_URL=http://localhost:8000
VITE_AUTH_URL=http://localhost:8001

# services/api-gateway/.env
DATABASE_URL=postgresql://user:pass@localhost:5432/aivo
JWT_SECRET=your-secret-key

Note: .env.local files are gitignored. Never commit secrets!

📚 Technology Stack

Frontend

• React 19 - UI library
• TypeScript 5.9+ - Type safety
• Vite - Build tool and dev server
• pnpm 10.18.2 - Package manager
• @tanstack/react-query - Data fetching and state management
• axios - HTTP client
• Material-UI (MUI) - Component library
• React Router - Client-side routing
• ESLint 9.37+ - Code linting
• Prettier 3.6+ - Code formatting
• Vitest 3.2+ - Testing framework

Backend

• FastAPI 0.104+ - Python web framework
• Python 3.11+ - Backend language
• PostgreSQL 14+ - Primary database
• Redis 7+ - Caching, sessions, and rate limiting
• SQLAlchemy 2.0+ - ORM with async support
• Alembic 1.12+ - Database migrations
• Pydantic 2.10+ - Data validation
• asyncpg - Async PostgreSQL driver
• Celery 5.3+ - Distributed task queue
• APScheduler 3.10+ - Job scheduling
• OpenAI API - AI content generation
• Ruff - Fast Python linter

Security & Monitoring

• python-jose - JWT authentication
• passlib - Password hashing
• Sentry - Error tracking
• Prometheus - Metrics collection
• OpenTelemetry - Distributed tracing
• Snyk - Security vulnerability scanning
• Trivy - Container security scanning
• ClamAV - Antivirus scanning
• fastapi-limiter / slowapi - Rate limiting

Infrastructure

• Terraform - Infrastructure as Code
• Docker - Containerization
• Amazon EKS - Kubernetes cluster management
• AWS S3 - File storage
• AWS RDS - Managed PostgreSQL
• AWS ElastiCache - Managed Redis

DevOps

• Turborepo 2.5+ - Monorepo build system
• pnpm workspaces - Dependency management
• GitHub Actions - CI/CD pipeline
• Docker - Container images for deployment
• Kubernetes - Container orchestration

🚀 CI/CD Pipeline

The AIVO platform uses GitHub Actions for continuous integration and deployment.

Pipeline Overview

Push/PR → Lint → Test → Build → Security Scan → Deploy

Environments:

• Staging (develop branch) - Auto-deploy to https://staging.aivo-platform.com
• Production (main branch) - Manual approval required → https://aivo-platform.com

Quick Commands

# Trigger staging deployment
git push origin develop

# Trigger production deployment (requires approval)
git push origin main

Pipeline Features:

• ✅ Automated linting (ESLint, Ruff)
• ✅ Backend tests with PostgreSQL + Redis
• ✅ Frontend tests with 80% coverage threshold
• ✅ Security scanning (Snyk, Trivy)
• ✅ Docker image building and pushing to ECR
• ✅ Kubernetes deployment with health checks
• ✅ Slack notifications

Documentation:

• Complete CI/CD Guide
• Quick Reference
• Secrets Setup

🎓 Feature Modules

Special Education Features

IEP Management:

• Digital IEP creation and management
• Goal tracking and progress monitoring
• Compliance with IDEA requirements
• Parent/guardian collaboration tools

Transition Services (High School):

• Work-Based Learning (Prompt 96) - Employer partnerships, job shadowing, internships, work-study programs
• Self-Determination Curriculum (Prompt 97) - 11-component curriculum, person-centered planning, SMART goals, decision-making skills
• Post-secondary goal setting and tracking
• Independent living skills assessment
• Career exploration and planning

Content Generation:

• AI-powered IEP goal generation
• Reading level adaptation (Flesch-Kincaid scoring)
• Content moderation and safety checks
• Compliance with COPPA and student privacy

Progress Monitoring:

• Real-time data collection
• Visual progress charts
• Automated compliance alerts
• Parent notification system

Accessibility:

• Text-to-speech integration
• Screen reader optimization
• Keyboard navigation
• High contrast modes
• Dyslexia-friendly fonts

Documentation

For detailed information about specific features, see:

• Work-Based Learning System
• Self-Determination Curriculum
• Quick Start Guides

🤝 Contributing

1. Create a feature branch: git checkout -b feature/my-feature
2. Make your changes
3. Run tests: pnpm test
4. Run linting: pnpm lint
5. Commit: git commit -m "feat: add my feature"
6. Push: git push origin feature/my-feature
7. Create a Pull Request

Commit Message Convention

We follow conventional commits for clear versioning:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• style: - Code style changes (formatting)
• refactor: - Code refactoring
• test: - Test updates
• chore: - Build process or auxiliary tool changes

📖 Documentation

• Turborepo Documentation
• pnpm Workspaces
• FastAPI Documentation
• React Documentation

📄 License

Copyright © 2025 AIVO AI Platform. All rights reserved.

---

Built with ❤️ for students with special needs