The first free, open-source, Turkish-language AI education platform for primary school children.

Mürebbiye (مربیه — governess, tutor) prepares Turkish children for an AI future. It bridges the gap between MEB's TYMM curriculum (which starts AI at grade 5) and the reality that children are already interacting with AI daily. Not a replacement for school — a wise companion that walks alongside the child.

For: Türk Gençliği — the next generation. Cost to families: Zero. Always.

Built with Next.js 15, React 19, Tailwind CSS, Prisma ORM, and AWS Bedrock (Claude Haiku). Generates personalized lessons from curriculum documents, provides an interactive student assistant, tracks learning metrics, enforces LLM budget caps, and sends parent email reports.

                  murebbiye.org
                       |
                  Vercel Edge
                       |
            Next.js 15 (App Router)
             /         |          \
    RDS PostgreSQL   S3 Bucket   AWS Bedrock
      (us-east-1)   (us-east-1)  (Claude 3.5 Haiku)

• Curriculum Upload -- Admin uploads PDF or Markdown files, which are parsed and chunked for LLM context
• Lesson Generation -- AI generates structured lessons (explain, guided practice, independent task phases) from curriculum chunks
• Student Assistant -- Interactive Q&A within lesson scope with out-of-scope detection
• AI Media Agent -- Two-stage pipeline (storyboard then generation) for diagrams, flowcharts, illustrations
• Budget Tracking -- Per-request LLM cost tracking with monthly and per-lesson caps, automatic mode degradation at 80%/100% thresholds
• Parent Reporting -- Automated email summaries with accuracy, hint dependency, and quality metrics
• Bilingual -- Full Turkish/English i18n for UI and reports
• Performance Monitoring -- API response time recording with median/p95 analysis

murebbiye/
├── app/                         # Next.js App Router
│   ├── (admin)/admin/           # Admin dashboard panels
│   ├── (student)/student/       # Student lesson UI
│   ├── api/
│   │   ├── admin/               # Admin API routes
│   │   │   ├── budget/          #   Budget status, simulate, reset
│   │   │   ├── curriculum/      #   Upload, list, retry
│   │   │   ├── lessons/         #   Draft generation
│   │   │   ├── media-agent/     #   Enrich, generate, review assets
│   │   │   ├── performance/     #   Summary, reset
│   │   │   └── reports/         #   Parent email dispatch
│   │   ├── auth/[...nextauth]/  # NextAuth endpoints
│   │   ├── health/              # Health check (DB connectivity)
│   │   └── student/             # Student-facing API
│   │       ├── assistant/       #   AI assistant Q&A
│   │       └── lessons/         #   Complete lesson, view media
│   ├── login/                   # Login page
│   └── layout.tsx               # Root layout
├── src/
│   ├── auth.ts                  # NextAuth configuration
│   ├── config/
│   │   ├── budget.ts            # Budget configuration
│   │   └── pilot.ts             # Pilot scope constants
│   ├── lib/
│   │   ├── assistant/           # Student assistant service
│   │   ├── budget/              # Budget tracking + ledger
│   │   ├── curriculum/          # Parser (PDF/MD), repository, service
│   │   ├── env.ts               # Zod-validated environment config
│   │   ├── i18n/                # Translation helpers
│   │   ├── lesson/              # Lesson generation + templates
│   │   ├── media-agent/         # AI media enrichment pipeline
│   │   │   ├── llm.ts           # Bedrock client wrapper
│   │   │   ├── orchestrator.ts  # Storyboard-to-generation pipeline
│   │   │   └── analyzer.ts      # Content analysis for media needs
│   │   ├── performance/         # Response time metrics
│   │   ├── prisma.ts            # Prisma client singleton
│   │   ├── reporting/           # Parent email composition + scoring
│   │   └── storage/s3.ts        # S3 upload/download wrapper
│   └── types/                   # Auth + vendor type declarations
├── prisma/
│   ├── schema.prisma            # Database schema (14 models, 10 enums)
│   ├── seed.ts                  # Seed admin + student users
│   └── migrations/              # SQL migration files
├── infra/                       # AWS CDK stack
│   ├── bin/                     # CDK app entry point
│   └── lib/                     # Stack definition (RDS + S3 + IAM)
├── scripts/
│   └── deploy.sh                # One-command infra deploy
├── tests/                       # Vitest test suite
├── docs/                        # Deployment + maintenance docs
├── docker-compose.yml           # Local dev PostgreSQL
├── vercel.json                  # Vercel deployment config
├── vitest.config.ts             # Test configuration
└── .github/workflows/ci.yml    # CI pipeline

• Node.js >= 20.17.0
• Docker (for local PostgreSQL)
• AWS credentials (for Bedrock LLM features)

# Clone
git clone https://github.com/JarvisOnM4/murebbiye.git
cd murebbiye

# Install dependencies
npm install

# Start local PostgreSQL
docker compose up -d

# Configure environment
cp .env.example .env
# Edit .env with your values (see Environment Variables section)

# Run database migrations
npx prisma migrate dev

# Seed initial users
npx tsx prisma/seed.ts

# Start dev server
npm run dev

The app runs at http://localhost:3000.

Default seed credentials (configure via .env):

• Admin: [email protected] / ChangeMe123!
• Student: [email protected] / ChangeMe123!

This is the recommended production setup. Vercel hosts the Next.js app (free tier), AWS provides the database, file storage, and LLM.

The infra/ directory contains an AWS CDK stack that creates:

• RDS PostgreSQL 16 (db.t4g.micro, SSL enforced)
• S3 bucket (versioned, encrypted, CORS configured)
• IAM user with Bedrock + S3 permissions
• Secrets stored in AWS Secrets Manager

# Prerequisites
npm install -g aws-cdk
aws configure  # Set up AWS credentials

# Bootstrap CDK (first time only)
cd infra
npm install
npx cdk bootstrap aws://<ACCOUNT_ID>/us-east-1

# Deploy
npx cdk deploy --require-approval broadening

Or use the convenience script from the project root:

chmod +x scripts/deploy.sh
./scripts/deploy.sh

Save the CDK outputs:

Retrieve secrets:

# DB password
aws secretsmanager get-secret-value \
  --secret-id murebbiye/db-credentials \
  --query 'SecretString' --output text | jq -r '.password'

# IAM secret key
aws secretsmanager get-secret-value \
  --secret-id murebbiye/iam-secret-key \
  --query 'SecretString' --output text

1. AWS Console > Amazon Bedrock > Model access
2. Request access to anthropic.claude-3-5-haiku-20241022-v1:0
3. Wait for approval (usually instant)

DATABASE_URL="postgresql://murebbiye_admin:<PASSWORD>@<ENDPOINT>:5432/murebbiye?schema=public&sslmode=require" \
  npx prisma migrate deploy

DATABASE_URL="<connection-string>" \
SEED_ADMIN_EMAIL="[email protected]" \
SEED_ADMIN_PASSWORD="<STRONG_PASSWORD>" \
SEED_STUDENT_EMAIL="[email protected]" \
SEED_STUDENT_PASSWORD="<STRONG_PASSWORD>" \
SEED_STUDENT_NICKNAME="Pilot Student" \
SEED_STUDENT_PARENT_EMAIL="[email protected]" \
  npx tsx prisma/seed.ts

# Link project
npx vercel link

# Deploy
npx vercel --prod

Set these environment variables in Vercel dashboard (Settings > Environment Variables):

In Vercel dashboard: Settings > Domains > Add murebbiye.org

Update your DNS registrar with the records Vercel provides (typically an A record or CNAME).

curl https://murebbiye.org/api/health
# {"status":"ok","service":"murebbiye","db":"connected","timestamp":"..."}

For developing without AWS (LLM features will not work):

docker compose up -d          # Start PostgreSQL
cp .env.example .env          # Configure environment
npx prisma migrate dev        # Run migrations
npx tsx prisma/seed.ts        # Seed users
npm run dev                   # Start dev server

Note: Bedrock-dependent features (lesson generation, student assistant, media agent) require valid AWS credentials even in local dev.

See .env.example for the complete list. Key variables:

14 models across the following domains:

# Create new migration (development)
npx prisma migrate dev --name <migration_name>

# Apply migrations (production)
npx prisma migrate deploy

# Check migration status
npx prisma migrate status

88 tests across 10 test files using Vitest.

npm test                    # Run all tests
npm run test:watch          # Watch mode
npm run test:coverage       # With coverage report

Tests cover: environment validation, curriculum parser, LLM cost computation, budget service logic, and performance metrics. All tests are pure-function unit tests that run without a database or AWS credentials.

GitHub Actions (.github/workflows/ci.yml) runs on push to main and on pull requests:

1. Install dependencies (npm ci)
2. Generate Prisma client
3. Validate Prisma schema
4. Lint (next lint)
5. Type check (tsc --noEmit)
6. Test (vitest run)
7. Build (next build)

Vercel auto-deploys from main when the GitHub repo is connected.

The budget system tracks LLM costs per request and enforces caps:

Caps reset at the start of each calendar month.

See docs/project-plan.md for the full plan.

Contributions are welcome — especially from Turkish-speaking educators and developers. See the roadmap above for what's being worked on.

If you want to help with curriculum content, translations, or unplugged activity guides, open an issue or reach out.

MIT