Ed-Tech Rostering App

A reference Laravel project for learning clean architecture, REST API design, database modeling, and React + Inertia frontends. Use it as a study guide, portfolio piece, or starting template.

---

What you'll learn

Topic	Demonstrated in this project
Layered architecture	Controllers → Services → Repositories → Models
Repository pattern	Interface bindings in AppServiceProvider
API Resources	Consistent JSON transformers
Authorization	AccessService with role + ownership rules
Dual authentication	Web sessions (Inertia) + Passport Bearer tokens
Database design	Normalized schema, pivot tables, soft deletes
React + Inertia	Role-based dashboards without a separate SPA
Testing	Feature tests for API access rules
Docker	One-command local environment

---

Quick start

Docker (recommended)

git clone <your-repo-url>
cd school-app
docker compose up --build

Service	URL
App	http://localhost:8000
Login	http://localhost:8000/login
API docs (HTML)	http://localhost:8000/docs
MySQL	localhost:3307

Demo data seeds automatically on first run. All demo passwords: password

Role	Email
Teacher	teacher@school.test
Teacher (1 class)	teacher2@school.test
Student	student@school.test

Local install

composer install
npm install && npm run build
cp .env.example .env
php artisan key:generate
php artisan migrate --seed
php artisan passport:client --personal --name="School App" --no-interaction
php artisan serve

---

Documentation

Guide	Description
docs/README.md	Documentation hub & learning path
docs/architecture.md	System architecture, ER diagrams, request flows
docs/api.md	Full REST API reference with examples
docs/openapi.yaml	OpenAPI 3.0 spec (Postman / Swagger)
docs/social-network-schema.md	Bonus: social network DB design exercise

Interactive API docs: http://localhost:8000/docs (Scribe)

Regenerate after API changes:

php artisan scribe:generate

---

Architecture at a glance

flowchart LR
    Browser["React + Inertia"] -->|"Pages"| Laravel
    Browser -->|"Bearer token"| API["/api/v1"]
    Laravel --> AccessService
    API --> AccessService
    AccessService --> Repositories
    Repositories --> MySQL[(MySQL)]

Loading

See docs/architecture.md for full diagrams.

---

API endpoints

Method	Endpoint	Description
POST	/login	Get Passport access token
GET	/api/v1/auth-user	Current user + role
GET	/api/v1/teachers/{id}	Teacher profile + classes
GET	/api/v1/students/{id}	Student profile
GET	/api/v1/students/{id}/activities	Student activity scores
GET	/api/v1/classes/{id}/students	Class roster (teachers only)

Full reference: docs/api.md

---

Project structure

app/
├── Http/Controllers/     # API + auth entry points
├── Http/Resources/       # JSON response transformers
├── Models/               # Eloquent models
├── Repositories/         # Data access layer
└── Services/             # Business rules (AccessService)

resources/js/
├── Pages/                # Inertia pages (Dashboard, Login, Student)
└── Components/           # Teacher/Student UI components

database/
├── migrations/           # Schema definitions
└── seeders/              # DemoDataSeeder

docs/                     # Architecture + API documentation
tests/Feature/            # API authorization tests

---

Testing

# All application tests
php artisan test --testsuite=App

# In Docker
docker compose exec app php artisan test --testsuite=App

Tests cover student/teacher access rules, class rosters, and activity visibility.

---

Docker commands

docker compose up --build          # Start app + MySQL
docker compose down                # Stop containers
docker compose down -v             # Reset database volume
docker compose exec app php artisan migrate:fresh --seed

---

Tech stack

• Backend: Laravel 11, PHP 8.2, Laravel Passport
• Frontend: React 18, Inertia.js, Tailwind CSS
• Database: MySQL 8.0
• API docs: Scribe (OpenAPI + Postman + HTML)
• DevOps: Docker Compose

---

Contributing

Contributions are welcome! Please open an issue or pull request.

1. Fork the repository
2. Create a feature branch
3. Add tests for behavior changes
4. Update docs/api.md if API routes change
5. Run php artisan scribe:generate and commit public/docs/

---

License

This project is open-source software licensed under the MIT License.