DOCUMENTATION · VERSION 1.1

Venus School Portal

The complete RTL school management script — installation, administration, teacher and student guides, customization and troubleshooting.

Framework

Laravel 12 · PHP 8.2+

Interface

Persian · RTL · Dark/Light

Roles

Admin · Teacher · Counselor · Student · Parent

Introduction

Venus School Portal is a complete school management system for Persian-speaking schools. It gives principals, teachers and students one consistent, app-like workspace: grades and report cards, attendance, online exams, assignments, timetables, a library, counseling, polls, messaging and rich progress analytics — all in a right-to-left interface with Jalali (Shamsi) dates, Persian digits, a dark theme and a mobile layout that feels like a native app.

Feature overview

Roles and access

Requirements

Installation

The package contains a ready-to-run application: dependencies (vendor) and compiled assets (public/build) are already included. Pick the method that matches your hosting.

A. Web installer (no command line)

Recommended for shared hosting. It needs only a browser.

The root .htaccess forwards every request to the public folder and blocks access to .env, vendor, storage and the database, so you do not need to change the document root on Apache/LiteSpeed. If your host lets you point the domain at public directly, that is slightly faster and equally supported.

B. Command-line installer

# inside the project folder
cp .env.example .env
php artisan key:generate
# clean school with your own administrator (asks for name, national code, password)
php artisan venus:install
# ...or the full demo school
php artisan venus:install --demo
# non-interactive
php artisan venus:install --first-name=Admin --last-name=School --codemeli=1234567890 --password=Str0ng-pass

The command creates the database file when you use SQLite, runs the migrations, creates the three grade levels (10, 11, 12) and your administrator. With --demo it seeds the demonstration data instead.

C. VPS / dedicated server (Nginx)

Point the server block at the public directory:

server {
    listen 80;
    server_name school.example.com;
    root /var/www/venus/public;
    index index.php;

    location / { try_files $uri $uri/ /index.php?$query_string; }
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }
    location ~ /\.(?!well-known).* { deny all; }
    client_max_body_size 60M;     # matches the 50 MB content upload limit
}

sudo chown -R www-data:www-data storage bootstrap/cache database
sudo chmod -R 775 storage bootstrap/cache database
php artisan venus:install

D. Local development

composer install
npm install
cp .env.example .env && php artisan key:generate
php artisan venus:install --demo
npm run build          # or: npm run dev
php artisan serve      # http://127.0.0.1:8000

Using MySQL / MariaDB

Create an empty database and user in your control panel, then either choose MySQL in the web installer, or edit .env:

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=venus
DB_USERNAME=venus_user
DB_PASSWORD=your-password

First steps after installing

A new school needs five things before teachers and students can work. Do them in this order:

Quick start for every role (your first 10 minutes)

New to Venus? Read only this chapter and do the steps for your own role, in order. Each step is short; the later chapters go deeper. The interface itself is in Persian, so menu names are given in English followed by the Persian label.

If you are the administrator

If you are a teacher

If you are a counselor or grade lead

If you are a student

If you are a parent

A school year with Venus

A suggested calendar so nothing is forgotten.

Online exams, step by step

Online exams let a teacher test students without paper or manual marking. Questions are either multiple choice (marked automatically) or descriptive (a written answer the teacher marks). Each student can take an exam once.

Create the exam (teacher or administrator)

Add questions

What students see

Students of that class (only that class) see the exam under Online exam, grouped as open, upcoming, done and missed.

• Opening the exam starts the clock; the countdown runs on the server, so closing or refreshing the page does not pause it.
• The bar “x of y answered” shows progress.
• Final submit — or the timer reaching zero — saves the answers (a 45-second grace period covers the automatic submit).
• After submitting, no second attempt is possible.

Results and marking descriptive answers

Multiple-choice marks are computed instantly. For descriptive questions, the exam page (Results and marking) shows a Mark descriptive button per student:

Other kinds of tests

• Written (offline) exams — for paper tests: Written exams → new exam → enter each student's mark. Ranks, the class average and the top three are produced automatically.
• Assignments — students upload a file or text, the teacher marks and comments (Assignments tab of the subject).
• Online class — register the meeting link (Meet, Zoom, Skyroom…) with a time; students see a “live” badge and their joins are logged. Venus does not host video itself.

Common exam problems

Bulk import and export

Instead of typing students one by one you can register the whole school from a spreadsheet (CSV) — each student together with both parents.

Exporting the student list

The same page offers Export student list: a CSV with the same columns (administrator: whole school; teacher and counselor: only their classes). Edit it in Excel and reuse it to import new students.

School profile

The administrator sets name, principal, phone, address, academic year and logo (PNG/JPG/WebP up to 1 MB) under School profile. The name and logo appear in the sidebar, browser tab title, the official report-card header and the {school} SMS variable. Tick Remove logo to delete it.

Administrator guide

Sign in at /login with a national code, password and the captcha code. Persian digits are accepted everywhere a number is typed.

Dashboard

The dashboard summarises the whole school and reacts to the grade and class filters at the top. Every card, chart and list is recalculated for the selection.

• KPI cards — number of students, active classes and grades, report-card completion, and the overall average with its change versus the previous term.
• Student profile card — students are ranked by GPA, best first. The arrows move through that ranking; choosing a grade or class jumps to the top student of that selection. Students without grades are shown with “—” and listed last.
• Progress chart — switch between by month and by grade and class; click a bar to drill down.
• Distribution and lists — performance tiers (excellent 18–20, good 16–18, average 14–16, needs effort <14) and the top / needs-attention lists.
• Weekly strip — this week’s exams and events on the Jalali calendar.

The search box in the header searches students by name (any order, e.g. “Amir Ahmadi”), national code, grade or class.

Grades and classes

• Add a class — class names are free text: 101, 107 or any word. A name must be unique inside its grade level. Persian digits are converted automatically.
• Edit — change name, field and capacity; delete a class only when it has no students.
• Copy subjects — duplicates the subject list (without teachers) of the first class in that grade.

Weekly timetable

Each class page contains a grid with the weekdays (Saturday–Thursday) as rows and up to eight periods as columns. Choose a subject for every cell and press Save timetable.

• Saving replaces the whole grid of that class.
• If the same teacher is already teaching another class in the same period, the save is rejected and the clash is listed (teacher, day, period, other class).
• Teachers see these periods when taking attendance and their weekly load on the teacher page.

Teachers and subjects

• Create a teacher with first name, last name, national code and password.
• Assign access — the edit page lists every subject with a checkbox per class (grouped by grade). Tick the classes the teacher should teach for that subject. Select all classes and None speed this up.
• Several subjects — one teacher can teach, for example, Mathematics in some classes and Physics in others. They switch between subjects in the header; all numbers shown to them are calculated for the active subject only.
• Transfers — ticking a class that already has another teacher for that subject moves it to this teacher.
• New subject — use Add a new subject for lessons that do not exist yet (for example Biology): name, unit weight (1–6) and the classes.

Students

The directory lists students with national code, class, average and status. Search accepts several words in any order. Open a student for the full profile: subject tabs, grades with edit/delete, assignment submissions, attendance, discipline records and the forms to record a grade, send an announcement or add a discipline entry.

Gradebook and report cards

1. Choose grade → class → subject → month → type (continuous, quiz, assignment, midterm, final).
2. For continuous work and quizzes you can keep several entries per month (Quiz 1, Quiz 2 …). Use the tabs above the table, or + New, and give each entry an optional title.
3. Type scores from 0 to 20 in steps of 0.25. Press Enter to jump to the next student. The count and live average are shown above the table.
4. Press Save. Only changed scores are written, and each student receives a notification.

Below the table the admin sees the official report cards of the class. Each card is a draft until you press Publish; students only see published cards. Use New report card to create one (title, up to which month, publish immediately).

The Announcement to the class form sends a notification to every student of the selected class.

Attendance

• Pick grade, class, subject, date (Jalali picker) and period. Periods scheduled in the timetable for that weekday are highlighted; other days allow a make-up entry.
• Set every student to Present, Absent, Late or Excused and add a reason if needed. “Present” leaves no record. Absent students are notified.
• Dates in the future are rejected. Recent entries can be edited or deleted from the list below.

Courses, content, exams and online classes

Each course page has four tabs:

• Assignments — title, description, deadline (Jalali), optional attachment. Students are notified. After the deadline you grade each submission (score and feedback) or enter a manual score for students who handed in on paper.
• Learning content — video, audio or PDF; upload a file (up to 50 MB) or paste a link.
• Online exams — set start, end and duration, then add questions.
• Online classes — title, join link (Google Meet, Skype, Adobe Connect …) and time; a “live” badge appears while it runs.

When creating assignments, content or online classes you can apply them to all classes of the same subject and grade with one tick.

Progress and distribution

Both pages follow the grade tabs at the top. Progress compares monthly averages and lists the six students with the largest rise and the six who need attention. Distribution counts students per performance tier per class. Students without grades are ignored in these statistics instead of being counted as zero.

Discipline records

From a student profile, record a warning, encouragement or delay with a title, optional description and a date. The record keeps who recorded it and when; the student sees it (with the recorder’s name and role) under Discipline and receives a notification.

Messages, notifications and profile

• Messages — inbox, sent items and compose, with an attachment (PDF, JPG, PNG, ZIP, DOC, DOCX up to 5 MB). The recipient search matches full names and shows class or subjects so people with the same name can be told apart. Students may write only to teachers and administrators.
• Notifications — the bell opens a slide-over with grades, announcements, new assignments, exams and messages.
• Profile and settings — name, avatar (image up to 2 MB), password change, display preferences.

Teacher guide

Teachers see the same dashboard, but everything is limited to the classes and subjects assigned by the administrator: the class list, the student directory, the class and subject pickers in the gradebook and attendance, exams, and the dashboard calendar.

Switching subjects

A teacher with two or more subjects sees the Active subject switch in the header of the dashboard, classes, students, progress and distribution pages. The averages, ranks, charts and student lists are calculated for the chosen subject only. The choice is remembered for the session.

Grading

Open Report cards & grades (the label for teachers is Enter grades). Only your own subjects appear. Enter scores exactly as described in the gradebook section — several quizzes per month are supported.

Taking attendance

Choose the class and subject, then the date. The periods your timetable schedules on that weekday are highlighted. Save the roll call; students marked absent or late are notified.

Course tools

Open Courses & content to create assignments, upload learning content, schedule online classes and build online exams for your subjects. Grade submissions and descriptive exam answers from the same pages.

Student profile actions

Opening a student of your class shows only your subject. From there you can record a grade, send a private announcement, enter a manual assignment score and add a discipline record. Opening a student who is not in one of your classes returns 403 Forbidden.

Student guide

Students sign in with the national code and password given by the school. The home screen shows rank in class and grade, the latest GPA, outstanding work, live classes and the GPA trend through the year.

On a phone

On screens narrower than 1024 px the sidebar becomes a bottom tab bar (Home, Assignments, Exams, Report card, More) and the stat cards become snap-scrolling carousels. The site can be added to the home screen.

Parents, counselors and SMS

This part of the portal connects the school with families. It is built around four ideas: parents have their own safe, read-only login; the admin decides what they see; SMS works through the pattern (template) system of Iranian gateways; and staff can send only what the admin allows.

Parent accounts and sign-in

When a student is registered the school enters the mobile number of the father and/or the mother (a name is optional; at least one mobile is required and the two numbers must differ). One account is created per mobile number; if the same mobile already belongs to another child, that account is linked to the new student too, so a family with several children has one login.

The parent home lists “what you should know” ordered by urgency (invitations, discipline, absences, a falling GPA, a subject that dropped, upcoming exams, praise), the GPA trend against the class average, per-subject movement, report cards, discipline and invitations. With several children a switcher appears at the top.

Counselors and grade leads

Admin → Counselors and grade leads creates a counselor and ticks the grades they are responsible for. A counselor sees only those grades’ classes and students on every page and in every chart; opening another grade’s student returns “403”.

What parents see (access levels)

Eight sections can be shown or hidden: report cards, marks, progress charts, discipline, absences, calendar and timetable, invitations, dashboard alerts. The most specific rule wins:

1. System default — Admin → Parent access (everything is visible until you change it).
2. Grade default — one card per grade; “apply to every student of this grade” clears individual exceptions.
3. Student exception — in the student profile; “back to grade setting” removes it.

School life: personal file, teaching reports, news and calendar

SMS settings and gateways

Only the admin opens Parent SMS. Choose a gateway, fill its credentials (secrets are stored encrypted), then for every event enter the pattern code approved in the gateway panel; the page shows the exact order of the variables to use when creating the pattern. A text fallback is used for gateways that accept plain text. Use Send test before enabling events.

The admin can also define ready-made messages (own text or pattern code). They appear in staff members’ permission lists and in the student profile as “Ready message”.

Who may send which SMS

• Teachers and counselors never type free text. They send only the built-in events and the ready-made messages the admin allowed for that person; free text is admin-only.
• In the permission matrix the admin can narrow an SMS permission, e.g. report-card SMS for continuous marks only, or discipline SMS for warnings only. A counselor can be limited to discipline SMS.
• Every recipient is limited to students in the sender’s own classes or grades; a daily cap protects against mistakes.

SMS setup step by step

Venus has no SMS line of its own; it connects to your account at an SMS provider (Kavenegar, SMS.ir…). Iranian service messages are sent through a pattern (template): you write the text once in the provider's panel and get it approved; Venus then sends only the pattern code and the variable values (name, date…).

What each gateway needs

Variable order per event

When a message does not arrive

Glossary

Frequently asked questions

A student or parent forgot the password. What now?

The administrator opens the student's file and creates a new password (same for a parent, or a counselor with the reset parent password permission). The new password is shown once.

A parent has two children at the school — two accounts?

No. Accounts are keyed by mobile number; registering the same number for the second child links it to the same account and the parent switches between children.

A student moved to another class — what happens to the marks?

Earlier marks stay with the old subjects; the new class's subjects start empty. Move the student from their file.

Can I run several schools from one install?

One install serves one school. Install each school in its own folder/domain.

Can parents change anything?

No. Parent accounts are read-only; they can only confirm their child's daily study and change their own password.

Can a teacher send any SMS?

No. Teachers and counselors send only the templates defined by the administrator, and only if the administrator allowed it. Free text is administrator-only.

Can students book counseling themselves?

No. Only the counselor/administrator schedules appointments; the student sees them.

If I close a section for parents, is the SMS still sent?

No. A closed section means no page, no SMS and no in-app notification.

How do I back up?

Copy two things: the database (database/database.sqlite or a MySQL dump) and the storage/app/public folder. See Updating.

Can I install Venus in a sub-folder (example.com/school)?

Yes. Extract everything into that folder, set APP_URL=https://example.com/school in .env and keep the .htaccess in the folder as shipped; the application detects its base path itself.

The site shows a 500 error after upload.

Set PHP to 8.2 or newer and check that storage and bootstrap/cache are writable; see Troubleshooting.

Are the font and sample images licensed?

Sample names and marks are fictional. Check the IRANYekanX font licence for your own use (see Credits and licenses).

May I resell or redistribute the script?

The standard licence covers one install on one domain; the exact text is in the bundled LICENSE.txt.

Configuration

All settings live in the .env file in the project root. The web installer writes it for you.

Upload limits

The application accepts attachments up to 5 MB (messages), 10 MB (assignments and submissions) and 50 MB (learning content). Your PHP limits must be at least as large: set upload_max_filesize and post_max_size (cPanel: Select PHP Version → Options).

Caching

If you edit views or configuration on the server, clear the caches: php artisan view:clear and php artisan config:clear. On hosts without a terminal, delete the files inside storage/framework/views.

Customization

Brand colours and themes

All colours are semantic design tokens in resources/css/app.css. Change --color-brand in the @theme block for the light theme and in :root.dark for the dark theme.

@theme {
  --color-brand: #4318ff;   /* primary colour */
  --color-canvas: #f4f7fe;  /* page background */
  --color-surface: #ffffff; /* cards */
  --color-mint: #05cd99;    /* positive */
  --color-rose: #ee5d50;    /* negative */
}
:root.dark { --color-brand: #7551ff; --color-canvas: #0b1437; --color-surface: #111c44; }

Logo

The mark is the single SVG resources/svg/logo_mark.svg (drawn with currentColor, so it follows the theme). Replace it with your own SVG. The favicon and PWA icon sit in public/.

Font

The interface uses the IRANYekanX variable font from resources/fonts, declared in resources/css/app.css. To use another font, add the files and edit the @font-face block and the --font-sans token.

Texts and translations

Interface texts are written directly in the Blade views under resources/views (Persian). Validation messages are in lang/fa/validation.php, including the field names under attributes. Navigation labels are in app/Support/Navigation.php.

Rebuilding the design

The compiled assets are already in public/build. After changing CSS, JavaScript or the Tailwind classes in a view, rebuild:

npm install
npm run build

Upload the new public/build folder to the server.

Adding a module

1. Create a controller in app/Http/Controllers and add its routes in routes/web.php inside the proper role group.
2. Create a view in resources/views using <x-layouts.app> and <x-page> — you get the sidebar, header, theme and mobile shell for free.
3. Add the menu entry in app/Support/Navigation.php.
4. Reuse the components x-stat, x-badge, x-empty, x-chart, x-tabs and x-jdate.

Architecture

Folder structure

How marks, GPA and ranks are calculated

1. Every grade is normalised to the 20-point scale: score × 20 / max_score.
2. A student’s subject average is the mean of their grades in that subject.
3. The GPA is the average of the subject averages weighted by each subject’s unit weight.
4. Class rank and grade rank compare GPAs inside the class / grade level. For a teacher, “GPA” means the average of the active subject only.
5. Students with no grades have no GPA: they show “—” and are excluded from distributions.

Role scoping

Routes are grouped by role: middleware. Inside the staff area, a teacher is further restricted by the courses assigned to them: lists, pickers, student profiles, exams and every POST are checked against those courses, returning 403 otherwise.

Dates

Dates are stored as Gregorian ISO values and displayed in Jalali with Persian digits. The x-jdate / x-datetime components render a Jalali picker that submits a Gregorian value. The helpers jd(), jtime() and fa() format dates and numbers in views.

Database

Security

• Authentication — national code + password + a single-use image captcha. Passwords are hashed (bcrypt). Sessions are regenerated at login.
• Brute-force protection — five failed attempts per minute for the same national code and IP lock that login for a minute.
• Authorisation — server-side role middleware plus per-course ownership checks for teachers; students can only open their own class’s courses, report cards and files.
• CSRF protection on every form; output escaped by Blade.
• Uploads — extension and size validated; stored outside the code; downloads go through authorised routes.
• Hardening — .env, vendor, storage, app and the database file are blocked from the web by the root .htaccess; APP_DEBUG=false hides stack traces.

Recommended checklist before going live

• Use HTTPS and enable Force HTTPS redirect in your control panel.
• Delete public/install.php and make sure APP_DEMO=false.
• Do not keep the demo data or demo passwords.
• Keep regular backups of the database and storage/app/public.
• Keep PHP updated.

Troubleshooting

First look at storage/logs/laravel.log — the last lines name the exact problem. Temporarily setting APP_DEBUG=true shows the error on screen; set it back to false immediately.

Updating

1. Back up .env, the database and storage/app/public.
2. Upload the new files over the old ones, except .env, database/*.sqlite and storage/.
3. Run php artisan migrate --force (or open the site — release notes tell you when a migration is needed) and php artisan view:clear.

Credits and licenses

Sample data (names, grades, books) is fictional and generated for demonstration. The default avatar and any sample photos are placeholders and may be replaced.

Changelog

Version 1.0.0

• First release: administrator, teacher and student portals, 20+ modules, dark/light themes, mobile shell.
• Web installer, venus:install and venus:reset-password.
• Weekly timetable builder with teacher clash detection; teachers with several subjects; role-scoped analytics.
• Gradebook with several quizzes per month; attendance by scheduled period; online exams with automatic and manual grading.
• Login throttling, Persian validation messages, Jalali date pickers, Persian-digit input.

Version 1.1.0

• Parent portal with mobile-based accounts (parent mobile + password only), progress/regression dashboard and “what you should know” alerts.
• Counselor / grade-lead role with a per-person permission matrix; counselors can register students and parents when allowed.
• Pattern-based SMS with eight Iranian gateways and a custom HTTP gateway; per-staff SMS permissions; ready-made messages; SMS log.
• Parent access levels at system, grade and student level; hidden sections send no SMS or notification.
• Parent password reset by admin or permitted counselor; creator recorded on registered students.
• Student personal file, teaching reports, grade news board, executive calendar, disciplinary rulebook, parent confirmation of study logs.
• Counselor-scheduled counseling appointments (no student self-booking) and student sign-in statistics.
• Comprehensive tabbed file, daily absence, homework board, study planner, cultural/research classes, paper exams, student groups, scheduled messages, live-class join log, support sign-in with audit log, quick access pins.
• Library desk, poll management, counseling programs, account housekeeping (edit, move class, new password, delete); final QA from a clean install.
• Active sessions list and optional two-factor sign-in (TOTP) for staff.
• School profile (name, logo, academic year) in the menu, report card and SMS; bulk import of students and parents from CSV with a per-row error report and a one-time password list; CSV export of the student list.
• Beginner step-by-step guides: quick start for every role, school-year calendar, online exams, SMS setup, glossary and FAQ.

Support

Before contacting support please read Troubleshooting and include the last lines of storage/logs/laravel.log, your PHP version and a description (or screenshot) of the problem. Thank you for choosing Venus.