# lauphilip/au-btech-coursebot-platform architecture

> Architecture diagram of the GitHub repository lauphilip/au-btech-coursebot-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lauphilip/au-btech-coursebot-platform
- Repository: https://github.com/lauphilip/au-btech-coursebot-platform

## Overview

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`](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/course_management.php) (Courses), [`api/auth_check.php`](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/auth_check.php) (Auth Check), [`analytics.php`](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/analytics.php) (Analytics), [`api/auth_handler.php`](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/auth_handler.php) (Auth Handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_index["Home<br/>entry page<br/>[index.php]"]
  node_login["Login<br/>auth page<br/>[login.php]"]
  node_teacher_dashboard["Dashboard<br/>staff page"]
  node_course_management["Courses<br/>staff page"]
  node_analytics["Analytics<br/>staff page<br/>[analytics.php]"]
  node_sidebar["Sidebar<br/>shared ui<br/>[sidebar.php]"]
end

subgraph group_api["API Layer"]
  node_auth_handler["Auth Handler<br/>api auth<br/>[auth_handler.php]"]
  node_auth_check["Auth Check<br/>api auth<br/>[auth_check.php]"]
  node_logout["Logout<br/>api auth<br/>[logout.php]"]
  node_fetch_registry["Registry Fetch<br/>api registry<br/>[fetch_registry.php]"]
  node_chat_engine["Chat Engine<br/>api ai<br/>[chat_engine.php]"]
  node_extract_course["Course Extract<br/>api ingest<br/>[extract_course.php]"]
  node_ocr_bridge["OCR Bridge<br/>api ingest<br/>[ocr_bridge.php]"]
  node_weaviate_proxy[("Weaviate Proxy<br/>api vector<br/>[weaviate_proxy.php]")]
end

subgraph group_platform["Platform"]
  node_style["Styles<br/>css<br/>[style.css]"]
  node_htaccess["Routing<br/>web config<br/>[.htaccess]"]
end

node_index -->|"sign in"| node_login
node_login -->|"submit"| node_auth_handler
node_auth_handler -->|"create session"| node_auth_check
node_auth_check -->|"gate"| node_teacher_dashboard
node_auth_check -->|"gate"| node_course_management
node_auth_check -->|"gate"| node_analytics
node_teacher_dashboard -->|"uses"| node_sidebar
node_course_management -->|"uses"| node_sidebar
node_analytics -->|"uses"| node_sidebar
node_teacher_dashboard -->|"styles"| node_style
node_course_management -->|"styles"| node_style
node_analytics -->|"styles"| node_style
node_course_management -->|"loads"| node_fetch_registry
node_course_management -->|"ingest"| node_extract_course
node_extract_course -->|"ocr"| node_ocr_bridge
node_extract_course -->|"index"| node_weaviate_proxy
node_chat_engine -->|"retrieve"| node_weaviate_proxy
node_chat_engine -->|"emit data"| node_analytics
node_fetch_registry -->|"read"| node_weaviate_proxy
node_auth_handler -->|"session end"| node_logout
node_htaccess -.->|"route"| node_login
node_htaccess -.->|"protect"| node_auth_handler

click node_index "https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/index.php"
click node_login "https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/login.php"
click node_teacher_dashboard "https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/teacher_dashboard.php"
click node_course_management "https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/course_management.php"
click node_analytics "https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/analytics.php"
click node_sidebar "https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/components/sidebar.php"
click node_style "https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/assets/style.css"
click node_htaccess "https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/.htaccess"
click node_auth_handler "https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/auth_handler.php"
click node_auth_check "https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/auth_check.php"
click node_logout "https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/logout.php"
click node_fetch_registry "https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/fetch_registry.php"
click node_chat_engine "https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/chat_engine.php"
click node_extract_course "https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/extract_course.php"
click node_ocr_bridge "https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/ocr_bridge.php"
click node_weaviate_proxy "https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/weaviate_proxy.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index,node_login,node_teacher_dashboard,node_course_management,node_analytics,node_sidebar toneBlue
class node_auth_handler,node_auth_check,node_logout,node_fetch_registry,node_chat_engine,node_extract_course,node_ocr_bridge,node_weaviate_proxy toneAmber
class node_style,node_htaccess toneMint
```

## Components

### Presentation

Server-rendered entry points and shared UI chrome.

- [Home](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/index.php): entry page · Public landing page. · `index.php`
- [Login](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/login.php): auth page · Credential entry and sign-in entry point. · `login.php`
- [Dashboard](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/teacher_dashboard.php): staff page · Primary authenticated staff overview. · `teacher_dashboard.php`
- [Courses](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/course_management.php): staff page · Interface for creating and managing course bots. · `course_management.php`
- [Analytics](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/analytics.php): staff page · Conversation and usage monitoring dashboard. · `analytics.php`
- [Sidebar](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/components/sidebar.php): shared ui · Reusable navigation chrome for authenticated pages. · `components/sidebar.php`

### API Layer

Protected PHP endpoints for auth, course operations, chat, and Weaviate access.

- [Auth Handler](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/auth_handler.php): api auth · Processes login and session creation. · `api/auth_handler.php`
- [Auth Check](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/auth_check.php): api auth · Validates access for protected actions and pages. · `api/auth_check.php`
- [Logout](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/logout.php): api auth · Terminates the active session. · `api/logout.php`
- [Registry Fetch](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/fetch_registry.php): api registry · Loads course and user registry data for management views. · `api/fetch_registry.php`
- [Chat Engine](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/chat_engine.php): api ai · Runs grounded course-bot conversations. · `api/chat_engine.php`
- [Course Extract](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/extract_course.php): api ingest · Normalizes uploaded course materials into structured metadata. · `api/extract_course.php`
- [OCR Bridge](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/ocr_bridge.php): api ingest · Converts documents and images into text for extraction. · `api/ocr_bridge.php`
- [Weaviate Proxy](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/api/weaviate_proxy.php): api vector · Server-side gateway to the semantic store and knowledge layer. · `api/weaviate_proxy.php`

### Platform

Web-server and static presentation support.

- [Styles](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/assets/style.css): css · Shared visual presentation layer. · `assets/style.css`
- [Routing](https://github.com/lauphilip/au-btech-coursebot-platform/blob/master/.htaccess): web config · Web-server rules for routing and access behavior. · `.htaccess`

## Connections

- 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.