How lauphilip/au-btech-coursebot-platform works
1. What this repo is
- A PHP-based university staff portal for managing “course bots”: AI assistants tied to specific courses, with student access control, course ingestion, chat, and analytics.
- The architecture is split into a small set of server-rendered pages plus an api/ layer that mediates all sensitive operations.
2. Top-level structure
- index.php, login.php, teacher_dashboard.php, course_management.php, and analytics.php are the main user-facing entry points.
- components/sidebar.php is shared UI chrome used across authenticated pages.
- assets/style.css provides the common presentation layer.
- .htaccess likely supports request routing and access/security behavior at the web-server level.
3. Frontend boundary
- The browser interacts with PHP pages for navigation and with API endpoints for actual work.
- README indicates the client-side layer uses vanilla JavaScript plus Chart.js and Marked.js, which implies interactive dashboards and markdown-rendered chat logs, while the PHP pages remain the main server-rendered shell.
4. Authentication and session control
- api/auth_handler.php, api/auth_check.php, and api/logout.php form the auth subsystem.
- login.php is the entry point for credentials, auth_handler.php performs login/session creation, auth_check.php gates protected actions/pages, and logout.php terminates the session.
- This is the primary boundary between public access and staff-only/admin access.
5. Course and registry management
- course_management.php is the staff-facing interface for creating or administering course-linked bots.
- api/fetch_registry.php likely reads course/user registry data from the backend store to populate management views.
- The README describes “UserRegistry” and “CourseRegistry” in Weaviate, so registry data is not just local state; it is an external persistent domain model.
6. Chat/agent subsystem
- api/chat_engine.php is the core runtime path for student/staff interactions with a course bot.
- This endpoint is the application’s main AI boundary: it likely receives a message, retrieves grounding context, constructs the prompt, and returns the bot response.
- The README positions this as “grounded” conversation, meaning chat is expected to be constrained by course-specific knowledge rather than open-ended LLM output.
7. Knowledge ingestion and extraction
- api/extract_course.php and api/ocr_bridge.php support turning raw course materials into structured course data.
- ocr_bridge.php suggests document/image OCR as an input step, and extract_course.php likely converts extracted text into normalized course metadata such as outcomes, ECTS, and faculty.
- This subsystem feeds the managed “course DNA” used elsewhere in the platform.
8. Vector/knowledge backend integration
- api/weaviate_proxy.php is the gateway to Weaviate, the vector database and graph-backed knowledge layer described in the README.
- The proxy pattern is important: the browser never talks to Weaviate directly; all access goes through PHP, which centralizes auth, filtering, and request shaping.
- This is the main persistence/semantic retrieval boundary for both course content and registries.
9. Analytics and observability
- analytics.php is the staff dashboard for monitoring student interaction patterns and bot quality.
- The README specifies word clouds, keyword frequency tracking, and full conversation inspection, so this page is likely powered by stored chat logs and rendered with charting/markdown tools.
- Architecturally, this is separate from chat runtime: it consumes interaction data rather than participating in the live response path.
10. Configuration and deployment model
- api/config.php.example indicates environment-specific secrets and service endpoints are expected outside version control.
- The app runs as PHP 8.x on a web server, with Weaviate and Mistral AI as the two key external services.
- The design is intentionally thin on backend frameworks: PHP acts as a secure orchestration layer, not a heavy application server.
11. Primary data flow
- Staff logs in through login.php → session is validated by auth_check.php → staff uses dashboards to manage courses and monitor analytics.
- Course materials are ingested through OCR/extraction → normalized metadata and documents are stored/indexed in Weaviate → the chat engine retrieves grounded context from Weaviate and sends prompts to Mistral AI.
- Analytics consume conversation records and metrics produced during chat interactions.
12. Main architectural takeaway
- The repo is organized around three clear planes: presentation pages, a protected PHP API layer, and external AI/data services.
- The key design pattern is “PHP as controlled mediator”: it authenticates users, proxies access to Weaviate, orchestrates Mistral calls, and keeps the AI and vector store behind server-side boundaries.
Main entry points: course_management.php Courses · auth_check.php Auth Check · analytics.php Analytics · auth_handler.php Auth Handler
Components 16
Presentation
Server-rendered entry points and shared UI chrome.
- Home · Public landing page.
index.php - Login · Credential entry and sign-in entry point.
login.php - Dashboard · Primary authenticated staff overview.
teacher_dashboard.php - Courses · Interface for creating and managing course bots.
course_management.php - Analytics · Conversation and usage monitoring dashboard.
analytics.php - Sidebar · Reusable navigation chrome for authenticated pages.
components/sidebar.php
API Layer
Protected PHP endpoints for auth, course operations, chat, and Weaviate access.
- Auth Handler · Processes login and session creation.
api/auth_handler.php - Auth Check · Validates access for protected actions and pages.
api/auth_check.php - Logout · Terminates the active session.
api/logout.php - Registry Fetch · Loads course and user registry data for management views.
api/fetch_registry.php - Chat Engine · Runs grounded course-bot conversations.
api/chat_engine.php - Course Extract · Normalizes uploaded course materials into structured metadata.
api/extract_course.php - OCR Bridge · Converts documents and images into text for extraction.
api/ocr_bridge.php - Weaviate Proxy · Server-side gateway to the semantic store and knowledge layer.
api/weaviate_proxy.php
Connections 22
- Home → Login: sign in · Users move from the public landing page to authentication.
- Login → Auth Handler: submit · Credentials are posted to the login processor.
- Auth Handler → Auth Check: create session · Login flow establishes and then verifies authenticated state.
- Auth Check → Dashboard: gate · Protected staff pages are accessed after auth validation.
- Auth Check → Courses: gate · Protected staff pages are accessed after auth validation.
- Auth Check → Analytics: gate · Protected staff pages are accessed after auth validation.
- Dashboard → Sidebar: uses · Authenticated pages share the common navigation shell.
- Courses → Sidebar: uses · Authenticated pages share the common navigation shell.
- Analytics → Sidebar: uses · Authenticated pages share the common navigation shell.
- Dashboard → Styles: styles · All major pages rely on the shared stylesheet.
- Courses → Styles: styles · All major pages rely on the shared stylesheet.
- Analytics → Styles: styles · All major pages rely on the shared stylesheet.
- Courses → Registry Fetch: loads · Management views pull registry data through the API.
- Courses → Course Extract: ingest · Course materials are processed into structured course data.
- Course Extract → OCR Bridge: ocr · Extraction can delegate text capture to OCR.
- Course Extract → Weaviate Proxy: index · Normalized course data is stored or updated in Weaviate.
- Chat Engine → Weaviate Proxy: retrieve · Chat grounding depends on semantic retrieval from Weaviate.
- Chat Engine → Analytics: emit data · Conversation activity feeds reporting and monitoring.
- Registry Fetch → Weaviate Proxy: read · Registry data is served from the semantic backend.
- Auth Handler → Logout: session end · Authentication flow is completed by explicit logout.
- Routing → Login: route · Web-server rules help direct requests into PHP entry points.
- Routing → Auth Handler: protect · Server rules likely reinforce access and request handling.