Getting started

This is the guide to read first. It takes you from an empty madrassa to one where teachers can take a register, parents can sign in and progress is being recorded, with everything in the order it actually needs doing. Set aside an hour or so; most of it is one-off work you’ll never repeat.

1. Getting your madrassa account

Makatib.App is in private beta, so accounts are opened with you rather than self-serve. Tell us about your madrassa on the Join the beta page and we’ll get in touch to set things up: classes, teachers, students and your Quran progress frameworks, ready before the first lesson.

When your account is created you’ll fill in a short form (Madrassa name, Your full name, Email, and a Password of at least eight characters) and click Create madrassa. Depending on your settings you either land straight on Admin → Overview, or see a “Check your inbox” message; open the confirmation link in that email and you’ll be taken there.

This first account is the management / admin account. It sees the whole madrassa and is the only role that can create classes, enrol students and invite people. Everyone else, teachers and parents alike, is invited from inside the app; they never sign up themselves.

Changing your own password: click your name at the bottom of the admin sidebar to open My account, then use the Change password section. Teachers do the same from My profile, and parents from the account menu in their portal. If you’re locked out rather than just changing it, use Forgot password? on the login page.

2. What to set up, in order

There’s no setup wizard; you work through the sidebar. This is the order that avoids doubling back, and it’s the order of the sections below:

1. Structure: year groups, then classes, then your term dates.
2. Students: enrol them one at a time, or upload the whole intake as a CSV.
3. Guardians: review the queued parents and send their portal invitations.
4. Teachers: invite them and tick the classes they teach.
5. Education: set the books and subjects teachers record progress against.

Only one thing is a hard prerequisite: a class must exist before you can tick it for a teacher, and before its name will match in a student CSV. Everything else is flexible. A student can be enrolled with No class and No year group and be sorted later, teachers can be invited before or after the students arrive, and term dates can be set at any point.

3. Year groups, classes and term dates

Go to Admin → Structure. There are two cards here.

Under Academic term, give each term a name plus a Start date and End date, then click Add term. You can prepare future terms in advance: the term containing today becomes current automatically and defines the attendance and task-completion summaries teachers see. Previous terms remain available in Structure and Reports. Creating or editing a term only changes the reporting window; it never changes or deletes attendance, task, progress, or enrolment records.

Academic structure is where the madrassa takes shape. Type a name into New year group (for example Year 4) and click Add year. Then use New class to add each class, such as Class 4B or Hifz 1, picking its year group from the dropdown. A class doesn’t need one: leave it on No year group and it will sit in a bucket of that name.

Below the forms, classes are listed under their year group with a live student count. Any year group or class name can be corrected later with the inline Rename link. There’s deliberately no delete here, because classes carry registers and progress history, so name them as you’d like them to read to teachers and parents.

4. Enrolling students one at a time

Go to Admin → Students and click Enrol student. Use this for a single new starter mid-term; for a whole intake, skip to the CSV in the next section.

Below that is the Guardians section, with room for up to four contacts per child (Add guardian adds another). Each needs a First name and Last name; the Relationship, Phone, Email and Address are optional but worth filling in. Three toggles decide what each contact can do:

• Primary contact: the main person to reach. One per child.
• Can receive messages: whether teachers can message them. On by default.
• Send portal signup link: only becomes available once you’ve typed an email address.

Important: on this form, Send portal signup link emails the parent immediately when you save. That’s the right behaviour for a one-off new starter, and the opposite of how the CSV works.

If the email you enter already belongs to a parent account in your madrassa (a sibling was enrolled last year, say), no second invitation is sent. The new child is simply added to that existing account, and you’ll see a note confirming it.

5. Bulk upload from a CSV

For a new intake, use Bulk upload (CSV) on the same page. One row per student, with that child’s guardians on the same row. Start from the students template, which has the header and one example row:

first_name,last_name,admission_number,preferred_name,date_of_birth,gender,
year_group,class,enrolment_date,status,track,guardian1_first_name,…

Yusuf,Khan,A1001,,2017-03-09,m,Year 4,Class 4B,2026-01-05,active,qaida,
Sara,Khan,mother,07700 900123,sara.khan@example.com,…,yes,no

(Shown wrapped for readability; in the real file each student is one long line. Open the template in Excel, Numbers or Google Sheets, fill it in, and export as .csv.)

Re-uploading is safe. Any row whose admission_number is already enrolled, or that repeats one earlier in the same file, is quietly skipped rather than treated as an error. Existing students are never overwritten by an upload, so to correct a detail, edit the student’s record rather than re-importing.

Uploads are partial by design: every valid row is saved even if others fail. You’ll get a summary of what imported, what was skipped, and a numbered list of any rows that didn’t, so you can fix just those and upload them again.

The one thing an upload never does is send email. Parents marked yes are added to an invitation queue instead, which you review and send yourself. That’s the next step.

6. Sending parent portal invites

Go to Admin → Guardians and click Invite parents. The button shows how many are waiting, for example “Invite parents (47 pending)”.

Inviting is deliberately a separate step: an email can’t be unsent, and a wrong address list sent to a hundred families at once is not a mistake you can take back. The dialog gives you two views, Queued from import (the parents your CSV marked) and All without portal access (everyone who could be invited). Tick individually or use the select-all row; parents with no email address are shown but can’t be selected. Then click Send N invitations.

Sends go out in batches of 20, with a running count so you can see progress. There’s also a limit of 80 invitations a day, which the dialog warns you about before you start if your selection is larger. Nothing is lost if you hit it: everyone successfully invited drops off the list, so reopening it tomorrow shows exactly the remainder.

If one address bounces or is rejected, the rest of the batch still goes. The reason is recorded against that parent so you can fix the address and try again.

What the parent receives

An email inviting them to the portal. Following the link asks them to choose a password, then drops them straight into it: child cards showing attendance, progress and tasks, plus messages from their child’s teacher. There’s nothing for them to set up.

If their email already has a parent account with you, no invitation is sent at all; their existing login simply gains the new child.

Reading the portal status

• No portal: a contact on file, with no portal access and nothing queued.
• Invite queued: marked for invitation, but nothing has been emailed yet.
• Invite sent: the email has gone; they haven’t set a password yet.
• Portal active: signed up and able to see their children.
• Inactive: access switched off, with contact and message history kept.

7. Adding teachers and assigning classes

Go to Admin → Teachers and click Add teacher. Fill in First name, Last name and Email (the three required fields), plus Phone, Job title, Start date, Address and Notes if you keep staff records here.

At the bottom is Assigned classes, a tick box for every class you’ve created. This is the only place classes are assigned; there’s nothing to do on the Structure page. A teacher can hold several classes, and a class can have several teachers. If the list is empty, go back and create your classes first.

The submit button reads Send invitation, and it means it: saving emails the teacher straight away. There’s no draft state, so add them when you’re ready for them to have access.

To change someone’s classes later, open their record and tick or untick. Saving replaces the whole set, so unticking a class is how you take it away. Teachers can also be made inactive from the roster without losing their history.

For a whole staff list, Bulk upload (CSV) works the opposite way round to the student one. You click Review import first and see exactly who would be invited, which rows were skipped and which need attention, and only then Confirm to send the emails. The header must match the template exactly and in order, class names go in one classes column separated by semicolons (Year 3; Hifz A), and it takes up to 200 teachers at a time.

What the teacher receives

An invitation email, a page to choose a password, and then their dashboard: the register for each class you ticked, their students, tasks, progress recording and messages with those students’ parents. Teachers see only their own classes; the wider madrassa view stays with management.

8. Next: your lessons, books and subjects

Everything above builds the roster: who is here, in which class, with which teacher and which parents. The last piece is what students are actually marked on, which means the Qaida, Nazra or Hifz book your madrassa reads, and any subjects taught alongside it like Fiqh or Arabic. That lives in Admin → Education.

Most madrassas need nothing more than the defaults there. If you teach from a specific book, or want to add subjects, the full walkthrough is in Setting up lessons, books & subjects, which covers the lesson-list CSV and per-class overrides.

Once that’s done you’re live: teachers take the register, record progress against real lessons, and parents see it in their portal the same evening.