🔄 Export Agent — Convert to Any Framework

IntelliStack ships with a built-in Export Agent (gitagent/) that lets any developer port the entire platform — or just one layer — to their preferred language and framework.

How it works — just ask in plain language:

"Convert IntelliStack to NestJS with Prisma"
"Port only the auth layer to Laravel"
"Give me the Go Fiber version of the RAG chatbot"
"Convert the database models to TypeORM"

The agent reads the live codebase, produces a migration plan, then outputs production-ready, framework-idiomatic code with all imports, env vars, and a wire-up checklist.

Start here: gitagent/workflows/convert.md · Example scenarios: NestJS · Django · Go Fiber

What Is IntelliStack?

IntelliStack is an AI-native Learning Management System purpose-built for Physical AI and Humanoid Robotics education. It replaces static course platforms with an intelligent, adaptive environment where learners progress through 5 gated stages — from foundational robotics concepts to a full capstone project — guided by a RAG-powered chatbot and a Socratic AI tutor at every step.

The problem it solves:

• Traditional LMS platforms have no AI layer — learners get stuck with no contextual help
• Robotics education content is scattered across docs, papers, and videos with no unified path
• Instructors have no visibility into where students struggle or how to adapt content
• Institutions lack the tools to manage cohorts, track progress, and deliver assessments at scale

How it works:

graph LR
    A[Student Signs Up] --> B[Personalized Onboarding]
    B --> C[Stage 1 Unlocked]
    C --> D{Learn via Lessons}
    D --> E[Ask RAG Chatbot]
    D --> F[Use AI Tutor]
    D --> G[Complete Assessment]
    G -->|Pass| H[Stage 2 Unlocked]
    G -->|Fail| D
    H --> I[...]
    I --> J[Stage 5 Capstone]
    J --> K[Certificate Issued]

Scale: The platform is architected to handle 10,000+ concurrent learners — async FastAPI backend with connection pooling, Redis-backed rate limiting and caching, Qdrant vector search with sub-50ms retrieval, and horizontally scalable Railway deployments.

🏗️ System Architecture

graph TB
    subgraph Client["Client Layer"]
        FE["Next.js 14 Frontend\n(Netlify)"]
        DOCS["Docusaurus Docs\n(GitHub Pages)"]
    end

    subgraph Auth["Auth Layer"]
        AUTH["Better-Auth OIDC Server\n(Railway · Node.js)"]
        JWKS["JWKS Endpoint\n/.well-known/jwks.json"]
    end

    subgraph API["API Layer"]
        BACKEND["FastAPI Backend\n(Railway · Python 3.11)"]
        MW["JWKS Middleware\nJWT Validation"]
    end

    subgraph AI["AI Layer"]
        RAG["RAG Pipeline\nQdrant + Cohere + OpenAI"]
        TUTOR["AI Tutor\nLangGraph · Socratic Method"]
        CHATKIT["ChatKit\nStreaming SSE"]
    end

    subgraph Data["Data Layer"]
        PG[("PostgreSQL\nNeon")]
        REDIS[("Redis\nCache + Rate Limit")]
        QDRANT[("Qdrant\nVector Store")]
    end

    FE -->|"OAuth / Session"| AUTH
    FE -->|"API Calls"| BACKEND
    DOCS -->|"Auth Redirect"| AUTH
    AUTH --> JWKS
    AUTH --> PG
    BACKEND --> MW
    MW --> JWKS
    BACKEND --> RAG
    BACKEND --> TUTOR
    BACKEND --> CHATKIT
    BACKEND --> PG
    BACKEND --> REDIS
    RAG --> QDRANT
    RAG -->|"OpenAI API"| CHATKIT

🔄 Request Flow

sequenceDiagram
    participant U as User
    participant FE as Next.js Frontend
    participant AUTH as Better-Auth OIDC
    participant API as FastAPI Backend
    participant AI as RAG / Tutor AI
    participant DB as PostgreSQL

    U->>FE: Visit intellistack-app.netlify.app
    FE->>AUTH: Sign In (Email / Google / GitHub)
    AUTH-->>FE: JWT Access Token (RS256)
    FE->>API: API Request + Bearer Token
    API->>AUTH: Verify via JWKS endpoint
    AUTH-->>API: Token valid
    API->>DB: Fetch user/content data
    DB-->>API: Data
    API->>AI: RAG query / Tutor session
    AI-->>API: Streamed response (SSE)
    API-->>FE: Response
    FE-->>U: Rendered content

🎓 5-Stage Learning Path

graph LR
    S1["Stage 1\nFoundations"]
    S2["Stage 2\nROS 2 & Simulation"]
    S3["Stage 3\nPerception & Planning"]
    S4["Stage 4\nAI Integration"]
    S5["Stage 5\nCapstone"]

    S1 -->|"Unlock"| S2
    S2 -->|"Unlock"| S3
    S3 -->|"Unlock"| S4
    S4 -->|"Unlock"| S5

    style S1 fill:#3B82F6,color:#fff
    style S2 fill:#22C55E,color:#fff
    style S3 fill:#EAB308,color:#000
    style S4 fill:#F97316,color:#fff
    style S5 fill:#EF4444,color:#fff

Each stage unlocks based on passing assessments in the previous stage. Progress is tracked at lesson, exercise, and assessment level with badge issuance and certificate generation upon completion.

🛠️ Technology Stack

Frontend

Backend

Auth Server

AI & ML

Infrastructure

✨ Key Features

🚀 Getting Started

Prerequisites

1. Clone

git clone https://github.com/SARAMALI15792/AINativeBook.git
cd AINativeBook

2. Configure Environment

cp intellistack/.env.example intellistack/.env
cp intellistack/auth-server/.env.example intellistack/auth-server/.env

Key values in intellistack/.env:

DATABASE_URL=postgresql://user:password@host:5432/intellistack
REDIS_URL=redis://localhost:6379/0
QDRANT_HOST=localhost
OPENAI_API_KEY=sk-...
BETTER_AUTH_URL=http://localhost:3001
BETTER_AUTH_SECRET=<min-32-random-chars>

3. Start Auth Server

cd intellistack/auth-server && npm install && npm run migrate && npm run dev
# Runs on http://localhost:3001

4. Start Backend API

cd intellistack/backend
pip install -r requirements.txt && alembic upgrade head
uvicorn src.main:app --reload --port 8000
# API docs: http://localhost:8000/docs

5. Start Frontend

cd intellistack/frontend && npm install && npm run dev
# Runs on http://localhost:3000

Or skip local setup and use the live app: intellistack-app.netlify.app

📖 How to Use the Platform

Students — Sign up → complete onboarding → work through Stage 1 lessons and exercises → ask the RAG chatbot for instant answers with source citations → use the AI Tutor when you're stuck (it guides, not gives away answers) → pass the assessment → Stage 2 unlocks → repeat through all 5 stages → receive your certificate.

Instructors — Log in with an instructor account → go to Content Authoring → write lessons in MDX with live preview → submit for review → once approved, content is automatically indexed into the RAG vector store → manage your cohort enrollments and view per-student progress analytics.

Admins — Log in with an admin account → manage institutions, cohorts, and user roles → monitor platform health and Prometheus metrics → configure external webhooks.

📁 Project Structure

AINativeBook/
├── intellistack/
│   ├── backend/                  # FastAPI Python backend
│   │   ├── src/
│   │   │   ├── main.py           # App entry point
│   │   │   ├── config/           # Settings & structured logging
│   │   │   ├── core/             # Domain modules (auth, users, content, learning, institution, assessment)
│   │   │   ├── ai/               # RAG, AI Tutor, ChatKit, Personalization
│   │   │   └── shared/           # DB, middleware, metrics
│   │   └── alembic/              # DB migrations
│   ├── auth-server/              # Better-Auth OIDC server (TypeScript/Node.js)
│   ├── frontend/                 # Next.js 14 App Router frontend
│   └── content/                  # Docusaurus learning content
├── specs/                        # Feature specs, plans, and task tracking
├── history/                      # Prompt History Records & ADRs
├── gitagent/                     # Export Agent — convert to any framework/language
│   ├── workflows/convert.md      # Main conversion workflow guide
│   ├── workflows/scenarios/      # NestJS, Django, Go Fiber worked examples
│   └── skills/                   # export-backend, export-auth, export-database, export-frontend, export-rag
└── .github/workflows/            # CI/CD (Railway + Netlify + GitHub Pages)

🧪 Testing

Frontend

cd intellistack/frontend
npm test              # Unit tests (Vitest)
npm run test:e2e      # E2E tests (Playwright)
npm run lighthouse    # Performance + accessibility audit

Backend

cd intellistack/backend
pytest

🚢 Deployment

All deployments are automated via GitHub Actions on push to main:

Required GitHub Secrets: RAILWAY_TOKEN, NETLIFY_SITE_ID, NETLIFY_AUTH_TOKEN, RAILWAY_AUTH_URL, RAILWAY_BACKEND_URL

📊 Implementation Progress

Phase 0  ████████████████████  Complete  — Vertical Slice
Phase 1  ████████████████████  Complete  — Setup & Infrastructure
Phase 2  ████████████████████  Complete  — Auth & Foundation
Phase 3  ████████████████████  Complete  — Student Learning (5-Stage Path)
Phase 4  ████████████████████  Complete  — Content Authoring
Phase 5  ████████████████████  Complete  — Institution Management
Phase 6  ████████████████████  Complete  — RAG Chatbot
Phase 7  ░░░░░░░░░░░░░░░░░░░░  Pending   — AI Tutor
Phase 8  ░░░░░░░░░░░░░░░░░░░░  Pending   — Community Features
Phase 9  ░░░░░░░░░░░░░░░░░░░░  Pending   — Assessment Engine
Phase 10 ░░░░░░░░░░░░░░░░░░░░  Pending   — Personalization
Phase 11 ░░░░░░░░░░░░░░░░░░░░  Pending   — Production Polish

Overall: 74.5% complete (38 / 51 tasks)

🤝 Contributing

1. Fork the repository and create a branch: git checkout -b <phase>-<feature>
2. Keep commits small and reference task IDs
3. Ensure tests pass before opening a PR against main

Code Standards: Python — PEP 8, type hints, async-first · TypeScript — strict mode · React — functional components only · DB — all schema changes via Alembic migrations

📄 License

MIT — see LICENSE