The Villagers — User manual

1. Getting started

The system has two halves. The public site needs no sign-in: fixtures, results, the league table, teams, players, photos, news and the prediction page. The back office is where the work is done and needs an account.

Signing in

1. Go to /login.
2. Enter your phone number the way you would write it on paper — 0791525931, no country code — and your password.
3. If you have no password, choose a one-time code. A 6-digit code is sent by SMS. It lasts 10 minutes and can be used once.

Demonstration accounts

These are created by the seed data so each role can be tried out. Type the number exactly as shown. The password for every one of them is password.

Finding your way

After signing in you land on the Dashboard. It shows only the tiles your role is allowed to act on, and each tile is a link to the screen that clears it. The menu down the left side works the same way — if you cannot see a section, your role does not have it.

2. Who can do what

3. Teams

Tournament Admin Super Admin

Adding one team

Go to Teams. A team needs a name and a district; everything else — crest, colours, home ground, chairman and coach contacts — can be filled in later.

Importing many teams at once

1. Prepare a spreadsheet and save it as CSV. The first row must be the column names.
2. Required column: name. Optional: short_name, abbreviation, district, sub_county, village, home_ground, founded_year, chairman_name, chairman_phone, coach_name, coach_phone.
3. On Teams, choose the file, optionally give the Season ID to register them all at once, and press Import.

A sample file is in the project at database/samples/teams-sample.csv.

Retiring a team

Teams are archived, never deleted. An archived team disappears from the lists but stays attached to every result it ever played, so old tables and statistics do not break.

4. Players and squads

Registering a player

Tournament Admin On Players, add a first name and surname. A photograph, date of birth, village and identification are all optional but each one makes an eligibility dispute easier to settle later.

Photographs are re-saved by the system, which removes any location data the phone attached to them. Minimum size is 300×300 pixels.

Squads

A squad is a team's list of players for one season. Shirt numbers are unique within a squad.

1. Team Manager submits the squad from My team. It is saved as pending.
2. Tournament Admin reviews it under Squad approvals and approves or rejects each entry. A rejection asks for a reason, which is sent to the manager.
3. Only approved players can be named in a match event.

After the season's squad cut-off date, no new players can be added except by a Super Admin — and that override is written to the audit log.

Duplicates

If you register a player whose identification number already exists, the system refuses and names the existing player. If the name and date of birth match someone already registered, you get a warning but can continue — two cousins in one village genuinely can share both.

5. Setting up a tournament

Tournament Admin Super Admin

The structure is four levels deep:

Knockouts that are not a power of two

96 teams do not divide evenly into a bracket. The Knockout planner on the Tournament screen works it out for you: enter the number of teams and it shows the bracket size, how many teams receive a bye, and every round that follows.

For 96 teams: 32 receive byes, 64 play a preliminary round to reduce to 32, and those 32 plus the 32 byes make the Round of 64 — then 32, 16, quarter-finals, semi-finals and the final.

Making the draw

The draw is made with a seed number. That means the same seed always produces the same pairings, so if anyone questions the draw you can re-run it in front of them and show that it comes out identically. The seed and the resulting pairings are written to the audit log. You can preview a draw before saving it, and optionally keep teams from the same district apart in the first round.

6. Fixtures

Tournament Admin

Creating fixtures

One at a time on the Fixtures screen, or generate a whole stage at once. Generation always shows you a preview first — nothing is saved until you confirm it.

For a league or group stage the generator produces a full round-robin, alternating home advantage so no team is away every week. For a knockout it makes the draw.

Warnings

If a team is already playing within 24 hours of the kick-off you are setting, or the venue is booked within three hours, you get a warning. It does not stop you — a double-header at one ground is sometimes deliberate.

Match officials

Assign a referee, assistants and a commissioner to each fixture. An official sees only the fixtures they are assigned to, and can only file a result for those.

Postponing and rescheduling

Both ask for a reason. The original kick-off is kept in the record. Both teams and every punter holding a slip on that fixture are sent an SMS.

7. Entering and confirming results

Filing a result from the ground

Match Official Open Enter a result on your phone.

1. Choose the fixture from your list.
2. Enter the full-time score. Half-time is optional.
3. Add the goals — scorer and minute — and any cards or substitutions. You can file the score alone, but the goals are what build the top-scorer table.
4. Press Submit.

If the goals you listed do not add up to the score you entered, the system says so before sending — correct one or the other.

Confirming

Tournament Admin Open Results. Everything waiting is listed with its score. Check it, then press Confirm.

An admin who enters a result directly confirms it in the same step, since the admin is the confirming authority.

Correcting a confirmed result

Super Admin only, and a written reason is required. The table, the bracket and the settlement are all recalculated from the corrected score.

Walkovers and abandoned matches

A walkover is recorded against whichever team is awarded it, with a reason, and scores 3–0 by default. An abandoned match records the minute and the decision — replay, award, or void. Either way, predictions on that fixture are voided.

8. The league table

The table is never typed. Every figure is calculated from confirmed results, and there is no screen anywhere in the system that lets anyone edit it directly.

Teams level on points are separated in this order:

1. Goal difference
2. Goals scored
3. Head-to-head record between the tied teams
4. Fewest red cards
5. Fewest yellow cards
6. Drawing of lots

That order is configurable per stage.

Points deductions

A deduction is applied to a team's registration with a reason. The table shows the earned points and the deduction separately, with a footnote — so the public can see both what was earned and what was taken away.

9. The prediction game

Creating an event

Tournament Admin On Prediction events:

1. Give the event a name — "Teams playing 15th–16th August 2026".
2. Tick the fixtures from the list. You never type a team name. The fixtures come from the fixtures module, so a slip is always tied to a real match.
3. Leave the closing time blank to close automatically 30 minutes before the earliest kick-off, or set your own.
4. Create it, then press Open when you want it live.

How a punter enters

On /prediction they type how many goals each team will score, give their name and Mobile Money number, confirm they are 18 or older, and submit. They immediately get a reference like TVS-4KX9-2026, on screen and by SMS.

If money is switched on, the slip stays pending payment until the money is matched to it. The punter sends the stake to the merchant number quoting that reference.

How slips are graded

By default a slip wins only if every score it predicted is exactly right. Two alternatives can be chosen per event: one correct score is enough, or a points system where an exact score scores more than a correct outcome.

If a listed fixture is postponed or abandoned, that fixture is voided. The event decides what happens next: void the whole slip and return the stake, or grade the fixtures that were played.

Closing and settling

Events close on their own at the closing time, and any slip still unpaid at that moment expires. Settlement runs by itself once the last fixture in the event has a confirmed result. Every punter gets an SMS with their outcome, and winners appear on the public leaderboard by first name and a masked phone number.

The exposure limit

Each event has a ceiling on what it could be asked to pay out. As slips come in, the Exposure button shows how close you are. Once the ceiling is reached the system refuses new slips rather than accepting a liability the organisation cannot cover.

10. Payments and payouts

Finance Officer

Matching money to slips

Reconciliation lists every slip waiting for payment. When a Mobile Money transfer arrives, find the slip by its reference or the punter's number, type the MoMo transaction reference into the row, and press Confirm. The slip goes live and the punter is sent an SMS.

Paying winners

No payout is ever automatic. A winning slip creates an entry in the Payout queue and waits there.

1. Check the payout. Press Approve — or Reject with a reason.
2. Large payouts need a second, different officer to approve as well.
3. Press Pay. Enter the MoMo reference if you sent it by hand, or leave it blank to use the Mobile Money API.

The daily check

The top of the Reconciliation screen shows the day's totals: slips taken, money staked, money paid out, and live exposure. The Dashboard shows Ledger balanced.

11. Photos and news

Content Editor Tournament Admin

Albums

1. On Media, create an album with a title and date. Copy the album ID it gives you.
2. Paste the ID into the upload box, choose your photos — as many as you like — and upload.

Photos are shrunk on your device before sending, which matters a great deal on a slow connection, and are re-saved on the server. Thumbnails are made in the background, so a photo may take a few seconds to appear.

Deleting a photo is reversible for 30 days before it is permanently removed.

Tagging

Tagging a photo with a player makes it appear on that player's profile. A player under 18 without recorded guardian consent cannot be tagged.

News and pages

Posts can be drafted, scheduled and published; a scheduled post goes live on its own. The Rules and Responsible Play pages carry a version number and an effective date, so a change to the rules is dated and visible rather than silent.

12. Reports and the audit log

Reports

On Reports, pick one and press Run to see it on screen, or Download CSV to open it in Excel.

The audit log

Every meaningful change is recorded: who did it, what their role was, when, from which address, and what the values were before and after. You can filter by action or date.

The audit log cannot be edited or deleted by anyone, including a Super Admin. That is deliberate: a record that the most powerful user can rewrite is not evidence of anything.

13. Settings

Super Admin

Settings holds the values you may want to change without a developer: the prediction cut-off, the grading rule, the cap on slips per punter, the threshold above which a payout needs two approvers, and the master switch for staked predictions.

Anything not set here falls back to the shipped default, which is shown on the same screen for reference.

14. If something goes wrong

Who to contact

Tournament and fixture questions: the Tournament Admin. Money questions: the Finance Officer. Anything the system itself is doing wrong: the developer, quoting what you were doing and the exact message on screen.