> For the complete documentation index, see [llms.txt](https://klassdocs.gitbook.io/klassapp-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://klassdocs.gitbook.io/klassapp-documentation/readme.md).

# KlassApp

**An open education protocol for humans and agents.**

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/KlassApp-Foundation/KlassApp/tree/main/LICENSE/README.md) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/KlassApp-Foundation/KlassApp)

KlassApp is an education protocol that runs in the tools educationists already use. Admins manage school operations in Slack, teachers enter marks from spreadsheets, and parents receive their children's school updates on WhatsApp, all by chatting in natural language with Toshi, your school's AI assistant.

The source is public on GitHub; supported self-hosting opens after an independent security review.

Live product: <https://klassapp.xyz>

![KlassApp admin dashboard with Toshi open on staging](https://3943025523-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fg6CnNihjBu6JNnwlAA6i%2Fuploads%2Fgit-blob-24c5b45271532d44f938dd7cf9def1241a40d0ff%2Fklassapp-screenshot-readme.png?alt=media)

## Key Capabilities

* **WhatsApp-first parent operations** — Live Meta Cloud API messaging: attendance, fees, results, interactive menus, and delivery logging. Parents get answers without calling the office.
* **Toshi, the school AI agent** — In-product assistant for guided school setup and role-aware workflows in the dashboard (with WhatsApp-channel capability in the product). Auditable, gated, and designed for human confirmation on sensitive steps.
* **Connected tools schools already use** — The admin surface is built around WhatsApp, Google Drive, and Slack as first-class channels. WhatsApp messaging is the connector shipping in production today; Drive and Slack are part of the same product model as the protocol expands.
* **Real school operations** — Academics, attendance, exams and report cards, fees, staff and parent roles, notice board, and a full onboarding wizard — all scoped per school.
* **Multi-tenant by design** — Every query, job, cache key, and UI list is scoped by `school_id`. Cross-school data leaks are treated as bugs, not edge cases.
* **Hosted or self-run** — Production SaaS on Laravel Cloud (`klassapp.xyz`, EU-West-1). This repository is MIT-licensed so you can read the code and run your own copy.

## Architecture: Toshi connector flow

How channels relate to the Laravel app today. **WhatsApp is the live connector** (Meta Cloud API). Google Drive and Slack appear in the product UI as first-class channels; they are not separate API clients in `app/` yet.

```mermaid
flowchart TB
  subgraph people [People]
    Parent[Parent on WhatsApp]
    Staff[Admin / Teacher in browser]
  end

  subgraph meta [Meta]
    CloudAPI["WhatsApp Cloud API<br/>graph.facebook.com"]
  end

  subgraph klassapp [KlassApp Laravel app]
    Inbound["WhatsAppController<br/>POST /api/whatsapp/inbound"]
    Outbound[OutboundWhatsAppService]
    Transport[WhatsAppBusinessService]
    DeliveryLog[(MessageDeliveryLog)]
    ToshiUI["AgentToshi Livewire"]
    ToshiSDK["ToshiSdkV2Service<br/>Laravel AI SDK"]
    DriveUI["Google Drive<br/>product model — UI only"]
    SlackUI["Slack<br/>product model — UI only"]
  end

  Parent <--> CloudAPI
  CloudAPI <--> Inbound
  CloudAPI <--> Transport
  Outbound --> Transport
  Transport --> DeliveryLog
  Inbound --> DeliveryLog
  Staff --> ToshiUI
  ToshiUI --> ToshiSDK
  Staff -.-> DriveUI
  Staff -.-> SlackUI
```

Inbound webhook and outbound Graph sends both go through Meta; delivery status is stored in `MessageDeliveryLog`. Dashboard staff talk to Toshi in-product; parent WhatsApp menus and proactive notices use the Meta path above (not a Drive/Slack API).

## Quick Start

KlassApp is a Laravel 12 application. There is no one-line install script. Local setup looks like a normal Laravel + Vite project.

### Requirements

* PHP 8.4+, Composer 2, Node.js 20+ (or current LTS), npm
* MySQL 8 and Redis 7 — or Docker Compose from this repo
* Git

### 1. Clone and install

```bash
git clone https://github.com/KlassApp-Foundation/KlassApp.git
cd KlassApp
composer install
cp .env.example .env
php artisan key:generate
npm ci
```

If `npm ci` fails on peer deps, this repo ships `.npmrc` with `legacy-peer-deps=true` for known Vue 2-era peer declarations. Prefer that over deleting packages without an audit.

### 2. Configure `.env`

Minimum for a local boot:

```ini
APP_URL=http://localhost:8000
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=klassapp_local
DB_USERNAME=root
DB_PASSWORD=

CACHE_STORE=file
SESSION_DRIVER=file
QUEUE_CONNECTION=database

# Optional: Toshi LLM (leave off for a plain UI smoke test)
TOSHI_LLM_ENABLED=false
OPENAI_COMPATIBLE_URL=
OPENAI_COMPATIBLE_API_KEY=
OPENAI_COMPATIBLE_MODEL=

# Optional: WhatsApp Meta Cloud API (only if testing messaging locally)
WHATSAPP_BUSINESS_API_TOKEN=
WHATSAPP_BUSINESS_PHONE_NUMBER_ID=
WHATSAPP_BUSINESS_WABA_ID=
WHATSAPP_BUSINESS_VERIFY_TOKEN=
```

### 3. Database and services

**Option A — Docker Compose** (app + MySQL + Redis + nginx; typically port 8080):

```bash
docker compose up -d
```

Point `DB_HOST` / Redis at the compose services when PHP runs inside the app container, or keep `127.0.0.1` when using published ports from the host.

**Option B — Host MySQL/Redis** matching the `.env` values above.

Then:

```bash
php artisan migrate
php artisan storage:link
```

Prefer factories and feature tests over production-like school data. Never use real student or parent records for verification.

### 4. Run the app

```bash
# Terminal 1 — Vite (writes public/hot while running)
npm run dev

# Terminal 2 — Laravel
php artisan serve
```

Open <http://127.0.0.1:8000>. For a production-like asset build without HMR:

```bash
npm run build
php artisan serve
```

Do not leave `public/hot` behind when testing a production-style build; Laravel will try to load assets from a dead Vite server.

### 5. Tests

```bash
php artisan test --compact
# focused:
php artisan test --compact tests/Feature/ExampleTest.php
```

PHPUnit is the project standard. UI checks use Playwright scripts under `e2e/`.

### Try the hosted demo

Staging is a separate Laravel Cloud environment with demo/seed data (not a production dump). Public login credentials are **not** published here.

* Staging URL: <https://klassapp-staging-7mpoqg.laravel.cloud>
* Request demo access: <community@klassapp.xyz>

## Resources

* [Live product](https://klassapp.xyz)
* [Documentation (GitBook)](https://klassdocs.gitbook.io/klassapp-documentation/) — community docs, architecture, and roadmap (synced from this repo)
* [Docs map](/klassapp-documentation/docs.md) — internal docs index (archived Docsify hub)
* [Architecture bridge](/klassapp-documentation/docs/architecture.md)
* [Public roadmap](/klassapp-documentation/docs/roadmap.md)
* [Contributing guide](/klassapp-documentation/contributing.md)
* [Agent & maintainer rules](/klassapp-documentation/agents.md)
* [Project provenance (GeGoK12 fork)](/klassapp-documentation/docs/project-provenance.md)
* [Code of Conduct](/klassapp-documentation/code_of_conduct.md)
* [Security policy](/klassapp-documentation/security.md)
* [DeepWiki overview](https://deepwiki.com/KlassApp-Foundation/KlassApp)
* Community: <community@klassapp.xyz>

### Stack (short)

| Layer         | Notes                                                         |
| ------------- | ------------------------------------------------------------- |
| PHP / Laravel | 8.4 / Laravel 12                                              |
| UI            | Blade, Livewire 3, Vue 3.5 via `@vue/compat` (MODE 2), Vite 8 |
| CSS           | Tailwind CSS 4 (CSS-first; no `tailwind.config.js`)           |
| Data          | MySQL 8, Redis 7                                              |
| Auth / API    | Session web auth, Laravel Sanctum                             |
| AI            | Laravel AI SDK + OpenAI-compatible LLM config for Toshi       |
| Production    | Laravel Cloud (`klassapp.xyz`, EU-West-1)                     |

Session history and verified ops notes live in [`knowledge.md`](/klassapp-documentation/knowledge.md) (maintainers).

## Contributing

1. Sync from latest `main` before starting (see [CONTRIBUTING.md](/klassapp-documentation/contributing.md)).
2. Prefer small, atomic PRs with real verification evidence.
3. Keep every feature multi-tenant (`school_id` end to end).
4. Do not commit secrets or real student/school data.

External contributor PRs get genuine human review before merge.

## License

KlassApp is released under the [MIT License](https://github.com/KlassApp-Foundation/KlassApp/tree/main/LICENSE/README.md).

**Copyright notices.** The original notice is retained unmodified, as the MIT License requires, with a second line covering the KlassApp work built on top of the fork:

* Original work (GeGoK12): Copyright (c) 2025 GegoSoft Technologies and GegoK12 Contributors
* KlassApp work (since the fork): Copyright (c) 2026 KlassApp Foundation

You are free to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, subject to the conditions in [`LICENSE`](https://github.com/KlassApp-Foundation/KlassApp/tree/main/LICENSE/README.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://klassdocs.gitbook.io/klassapp-documentation/readme.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.