Getting started

This is the guide to read first. It takes you from an empty madrassa to one where teachers can take a register, learners and families 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 Get started page and we’ll get in touch to set things up: classes, teachers, students and your Quran or subject 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. Teachers, adult learners, parents and guardians are invited from inside the app; they do not create an unlinked account 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 adult learners or guardians 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. Education: choose Quran and subjects or Subjects only as your curriculum mode.
3. Students: enrol them one at a time, or upload the whole intake as a CSV.
4. Portal access: review adult learner accounts and queued guardian invitations.
5. Teachers: invite them and tick the classes they teach.
6. 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 Working week, choose the days when classes normally teach. This is the default used to decide when a register is expected. If one class follows a different recurring timetable, open that class later under Admin → Classes and set its custom week; all other classes continue to inherit the madrassa default.

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 open Admin → Classes and use Add class to create 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.

Structure shows a read-only class overview under each year group, with a live student count. Correct a year-group name here with Rename. To correct a class name or move the whole class to another year group, use Edit on the Classes page. There’s deliberately no delete here, because classes carry registers and progress history.

Once students exist, use Admin → Classes to open a roster, move several students, assign teachers or prepare the next set of class placements. See Managing classes & rollover for that workflow.

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.

For an under-18 student, the Guardians section has room for up to four contacts (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,address_line1,address_line2,city,
postcode,country,self_portal_email,guardian1_first_name,…

Yusuf,Khan,A1001,,2017-03-09,m,Year 4,Class 4B,2026-01-05,active,qaida,
12 High Street,,Leeds,LS1 4DY,United Kingdom,
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.

With automatic numbering switched on, a blank admission_number receives the next available number during import. Supply a number when you need to preserve an existing identifier.

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. Preparing Student and Parent Portal access

Send parent and guardian invitations

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.

Prepare adult learner accounts

The same Guardians area lists learners who turn 18 within the next 30 daysand adult records needing review. Enter the learner's own email address and send their Student Portal invitation. Their access becomes available from the eighteenth birthday, never before it.

A parent or guardian linked before that date keeps Full access by default. The learner can change that person to Finance only for the fee view or No access, and can restore full access later. A guardian linked after the learner is already 18 starts with no access until a choice is recorded. A staff-recorded instruction requires a short evidence note describing how and when it was given.

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. You can make the same live assignment from the teacher's record or from the relevant class under Admin → Classes; Structure is only for creating and naming classes. 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. Under Admin → Education, choose Quran and subjects for dedicated Qaida, Nazra or Hifz pathways, or Subjects only for an Arabic school, a subject-led weekend school or another subject-led programme. Then configure the books and lesson sets teachers will use.

Traditional madrassas can use the default Quran frameworks. If you teach from a specific book or use a subjects-only curriculum, 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 adult learners or authorised guardians see it in their portal.