Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Elian-D/ORVIAN/llms.txt

Use this file to discover all available pages before exploring further.

This quickstart walks you through spinning up a complete ORVIAN development environment on your local machine. By default ORVIAN uses SQLite, so you do not need a running MySQL server, a Docker daemon, or any external service to get the application up and running. All you need is PHP, Composer, and Node. Docker is listed as optional for teams that want MySQL or Redis parity with production from day one.
1

Install Prerequisites

Make sure the following tools are available on your machine before proceeding:
ToolMinimum versionNotes
PHP8.2With pdo_sqlite, mbstring, xml, curl, gd extensions
Composer2.xgetcomposer.org
Node.js18 LTSRequired to build the Tailwind/Vite frontend
GitAny recentFor cloning the repository
Docker (optional)24+Only needed if you want MySQL + Redis in dev
Verify your PHP version:
php -v
# PHP 8.2.x (cli)
2

Clone the Repository

git clone https://github.com/Elian-D/orvian.git && cd orvian
The repository contains the full Laravel 12 application, Livewire components, Blade views, and the composer.json scripts that drive the entire local workflow.
3

Copy the Environment File

cp .env.example .env
Out of the box, .env.example sets DB_CONNECTION=sqlite with the host/port/name fields commented out. This means Laravel will automatically use database/database.sqlite — no database server required.
For production or MySQL-based local development, uncomment the DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, and DB_PASSWORD lines and change DB_CONNECTION to mysql. You will also want to configure the third-party service variables at the bottom of the file (FACIAL_API_URL, CHATWOOT_*, EVOLUTION_API_*) before enabling those modules.
Key environment variables to review for a first-time local setup:
APP_NAME=Laravel
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost

DB_CONNECTION=sqlite        # Default — no DB server needed

QUEUE_CONNECTION=database   # Jobs run via DB, not Redis
CACHE_STORE=database        # Cache in DB, not Redis

# Optional biometric microservice
FACIAL_API_URL=http://host.docker.internal:8001
FACIAL_API_KEY=your-secret-key

# Optional WhatsApp alerts
EVOLUTION_API_URL=https://evolution.orvian.com.do
EVOLUTION_API_KEY=evolution_api_key_12345

# Notification thresholds
ALERT_ABSENCE_THRESHOLD=3
ALERT_TARDINESS_THRESHOLD=3
4

Run composer setup

composer setup
This single command runs the following sequence automatically:
  1. composer install — downloads all PHP dependencies from vendor/
  2. php -r "file_exists('.env') || copy('.env.example', '.env');" — copies .env.example to .env if no .env file exists yet
  3. php artisan key:generate — writes APP_KEY into your .env
  4. php artisan migrate --force — creates all database tables (SQLite file is created if missing)
  5. npm install — installs all Node packages including Vite, Tailwind, and Alpine.js
  6. npm run build — compiles and fingerprints all frontend assets into public/build/
The command takes approximately 60–90 seconds on a first run. Once it completes, the application is fully seeded with the Owner account structure and is ready to serve requests.
5

Start the Development Stack

composer dev
This command uses npx concurrently to launch four processes in parallel, each color-coded in the terminal:
ColorProcessCommand
🔵 BlueLaravel HTTP serverphp artisan serve
🟣 PurpleQueue workerphp artisan queue:listen --tries=1 --timeout=0
🔴 RedLog tail (Pail)php artisan pail --timeout=0
🟠 OrangeVite dev server (HMR)npm run dev
All four processes share the same terminal window. Stopping one (Ctrl+C) stops all of them (--kill-others flag). The queue worker is particularly important: Excel imports, WhatsApp alerts, and biometric encoding jobs all run asynchronously through the database queue.
6

Complete the Owner Installation

Open your browser and navigate to:
http://localhost:8000/register
This is the Owner self-installation screen — it only appears once, on a fresh installation with no Owner account yet created. Fill in your name, email, and password to create the platform’s superadmin account.After registration you will be redirected to the Admin Hub at /admin/hub, where you manage all schools on the platform.
7

Configure Your First School

From the Admin Hub, click New School or navigate directly to:
http://localhost:8000/admin/setup
The School Setup Wizard walks you through five steps:
  1. Plan selection — choose the feature tier for this school
  2. School details — name, MINERD code, province, municipality, shift (tanda)
  3. Academic structure — select active levels and grades; the wizard auto-generates sections
  4. Academic year — start and end dates (calculated from the current month by default)
  5. Director account — creates the school’s principal user and fires the SchoolConfigured event, which bootstraps the full academic structure asynchronously
Once the wizard completes, the Director can log in at http://localhost:8000 and access the school panel at /app/dashboard.

​
Running Tests

ORVIAN’s test suite is built with Pest v4. Tests use an in-memory SQLite database by default, so they run without any database server. 
# Run the full suite (clears config cache first)
composer test

# Run a single test by name filter
php artisan test --filter=SomeName

# Run a specific test file
php artisan test tests/Feature/Attendance/PlantelAttendanceTest.php
composer test is equivalent to: 
php artisan config:clear --ansi && php artisan test
The config-clear step ensures that any cached configuration from a previous run does not interfere with the test environment.

​
Demo Data

For development and UI testing, ORVIAN ships with a master demo seeder command that generates realistic attendance history for a school. 
php artisan orvian:seed-demo --school_id=1 --students=75 --days=30

​
Parameters

ParameterTypeDefaultDescription
--school_idinteger(required)The database ID of the school to seed. Find it in /admin/schools.
--studentsinteger75Number of students to create and distribute across active sections. Maximum 150.
--daysinteger30Number of calendar days of attendance history to generate, counting back from today. Weekends are automatically skipped.
--freshflagfalseDestructive. Deletes all existing attendance records for the school before seeding. Never use on a school with real data.

​
What the seeder generates

The command runs in five sequential phases:
  1. Students — creates up to 150 students (Dominican Spanish names) distributed evenly across active sections. QR codes are generated automatically by StudentObserver.
  2. Teachers — creates three demo teachers: María González, Carlos Reyes, and Ana Castillo (uses firstOrCreate, safe to re-run).
  3. Subjects & Assignments — creates or reuses Lengua Española, Matemáticas, and Ciencias Sociales. Generates a TeacherSubjectSection record for every teacher × section × academic year combination.
  4. Attendance Records — for each business day in the range, generates DailyAttendanceSession, PlantelAttendanceRecord, and ClassroomAttendanceRecord rows in bulk chunks of 200. Plantel distribution: 80% present, 10% late, 5% absent, 5% excused. Classroom distribution for present students: 75% present, 10% late, 10% absent (triggers pasilleo detection), 5% excused.
  5. Excuses — creates 3 approved AttendanceExcuse records on random students.
The --fresh flag prints an explicit console warning before deleting records. It is intended only for development reset workflows. Never run it against a school with real attendance data.

​
What’s Next

Architecture

Learn how ORVIAN’s modular monolith is structured — directory layout, Livewire patterns, the service layer, and how multi-tenancy is enforced at the Eloquent level.

Multi-Tenancy

Deep dive into how each school is isolated as a tenant: global scopes, IdentifyTenant middleware, and how Spatie Permission’s teams mode is used with school_id.

Attendance Module

Understand the dual-domain attendance model (Plantel + Aula), cross-validation rules, the three capture methods, and how the daily session lifecycle works.

Academic Module

Explore student and teacher management, the SIGERD Excel importer, biometric enrollment, and how subjects are assigned to teachers by section and academic year.

Build docs developers (and LLMs) love

Get started for freeTalk to us