A digital queue for government service offices (passports, visas, permits). Applicants join from their phone and follow their place in line live. Officers call the next person from a dashboard, a TV in the waiting room shows who is being served, and the applicant gets an email when it is their turn.
Nobody has to stand in a physical line, and nobody misses their turn because they stepped outside.
- Features
- Screenshots
- Quick start with Docker
- Local setup without Docker
- How it works
- Wait time estimates
- Data model
- Routes and JSON endpoints
- Project layout
- Configuration
- Tests and CI
- Design decisions
- Ideas for next steps
For applicants (no account needed)
- Join a queue online. Pick a service and get a number such as
PR-004. The form already shows how many people are waiting for each service and roughly how long it will take. - Live status page. Your number, how many people are ahead of you, an estimated wait in minutes, and who is being served now. It updates itself every 5 seconds and has a mobile-first layout.
- Email when called, sent through Laravel's queue so a mail problem never blocks the officer.
- Leave the queue if plans change, so everyone behind you moves up.
For officers
- Dashboard with today's numbers (waiting, at the counter, served today, average minutes per person) and one panel per service.
- Call next takes the oldest waiting person, and Mark as complete finishes them. Each step is timestamped.
- Officer accounts are created from the command line. There is no public sign-up page.
For the waiting room
- Display board at
/board, built for a TV: big numbers, high contrast, a clock, the next three numbers per service, and a flash when a new number is called. It shows queue numbers only, never names or emails.
Engineering
- 25 feature tests (73 assertions), run on PHP 8.2 and 8.3 on every push
- Laravel Pint code style check in CI
- Docker image with a one-command demo, also started and checked in CI
- Race-condition safe: queue numbers and "call next" both run inside locked database transactions
| Join the queue | Officer dashboard |
|---|---|
![]() |
![]() |
Waiting-room display board
git clone https://github.com/kinuthia-mark/Equeue-project.git
cd Equeue-project
docker compose up --buildOpen http://localhost:8000. The compose file loads demo data: five services with sample queues and a demo officer, officer@example.com / password. The display board is at http://localhost:8000/board.
The SQLite database lives in a named volume (equeue-db), so queues survive a restart. docker compose down -v resets everything.
The image is production-style:
- Apache + PHP 8.3 serving only Laravel's
public/folder, with OPcache on and PHP's productionphp.ini APP_ENV=productionandAPP_DEBUG=falseby default, so errors never show stack traces to visitors- config, routes and views are cached at start-up
- Apache and PHP version banners are switched off
- a health check on Laravel's
/uproute
DEMO_DATA=1 (set in the compose file) only adds the demo officer and sample queues.
Requirements: PHP 8.2+ with the sqlite3 extension, and Composer.
git clone https://github.com/kinuthia-mark/Equeue-project.git
cd Equeue-project
composer install
cp .env.example .env
php artisan key:generate
touch database/database.sqlite
php artisan migrate --seed
php artisan serveOpen http://localhost:8000.
Public registration is disabled so strangers cannot control your queues.
- Local development:
--seedcreates the demo officer (officer@example.com/password) and sample queues. This only happens whenAPP_ENV=local. - Anywhere else: create officers from the command line. You will be asked for a password.
php artisan officer:create jane@office.go.ke --name="Jane Wanjiru"Officers log in at /login and land on /officer.
Three kinds of screen use the same data: the applicant's phone, the officer's dashboard and the waiting-room TV.
flowchart LR
A[Applicant phone] -->|1. Join queue| S[eQueue app]
S -->|2. Queue number + status page| A
O[Officer dashboard] -->|3. Call next| S
S -->|4. Email: it is your turn| A
S -->|5. New number on screen| T[Waiting-room TV /board]
O -->|6. Mark complete| S
sequenceDiagram
actor A as Applicant
participant W as Web app
participant D as Database
actor O as Officer
participant B as Display board
A->>W: Submit name, email, service
W->>D: Lock service, next number, insert (waiting)
W-->>A: Redirect to /status/{uuid}
loop every 5 seconds
A->>W: GET /status/{uuid}/json
W-->>A: ahead, estimate, now serving
end
loop every 4 seconds
B->>W: GET /board/json
W-->>B: now serving + next 3, per service
end
O->>W: Call next
W->>D: Lock oldest waiting, set in_service + called_at
W-->>A: Email: it is your turn (queued)
O->>W: Mark as complete
W->>D: Set completed + completed_at
stateDiagram-v2
[*] --> waiting: applicant joins
waiting --> in_service: officer presses Call next
waiting --> cancelled: applicant leaves the queue
in_service --> completed: officer presses Mark as complete
completed --> [*]
cancelled --> [*]
The estimate on the status page is:
minutes left = (people ahead + 1 if someone is at the counter) × average service time
The average service time for a service is the mean of completed_at - called_at over the 20 most recently completed entries for that service. Until a service has any history, it uses QUEUE_DEFAULT_SERVICE_MINUTES (5 by default). Each service learns its own pace, so a quick status inquiry does not inflate the estimate for a passport application.
The logic lives in QueueEntry::averageServiceMinutes() and QueueEntry::estimatedWaitMinutes() and is covered by tests.
erDiagram
USERS {
bigint id PK
string name
string email UK
string password
}
QUEUE_ENTRIES {
bigint id PK
uuid token UK "used in the status URL"
string name
string email
string service "slug from config/services_list.php"
int service_number "1, 2, 3 ... per service"
string queue_number UK "e.g. PR-004"
string status "waiting, in_service, completed, cancelled"
timestamp called_at
timestamp completed_at
timestamp created_at
}
users are officers. queue_entries are applicants. The two tables are deliberately independent: applicants never have an account. There is an index on (service, status) because almost every query filters on both.
| Method | Path | Who | Purpose |
|---|---|---|---|
| GET | / |
Public | Join form with queue lengths |
| POST | /submit |
Public, max 10 per minute per IP | Join a queue |
| GET | /status/{token} |
Public, needs the UUID | Live status page |
| GET | /status/{token}/json |
Public, needs the UUID | Status data polled by the page |
| POST | /status/{token}/leave |
Public, needs the UUID | Leave the queue |
| GET | /board |
Public | Waiting-room display |
| GET | /board/json |
Public | Display data polled by the board |
| GET | /officer |
Officer | Dashboard |
| POST | /officer/call-next |
Officer | Call the oldest waiting person for a service |
| POST | /officer/complete/{token} |
Officer | Finish the person at the counter |
| GET | /up |
Public | Health check (used by Docker) |
Example /status/{token}/json response:
{
"status": "waiting",
"status_label": "Waiting",
"ahead": 1,
"now_serving": "PR-007",
"estimated_wait_minutes": 11
}Example /board/json response (one service shown):
{
"services": [
{
"slug": "passport-renewal",
"label": "Passport renewal",
"now_serving": "PR-007",
"up_next": ["PR-008", "PR-009"],
"waiting": 2
}
],
"updated_at": "2026-10-06T09:15:00+03:00"
}flowchart TD
R[routes/web.php] --> AC[ApplicantController]
R --> OC[OfficerController]
R --> BC[BoardController]
AC --> M[QueueEntry model]
OC --> M
BC --> M
OC --> MAIL[NowServing mail]
M --> DB[(SQLite)]
| Path | Purpose |
|---|---|
routes/web.php |
All routes |
app/Http/Controllers/ApplicantController.php |
Join form, status page, leave queue |
app/Http/Controllers/OfficerController.php |
Dashboard and stats, call next, complete |
app/Http/Controllers/BoardController.php |
Waiting-room display and its JSON feed |
app/Models/QueueEntry.php |
Statuses, position, average service time, wait estimate |
app/Mail/NowServing.php |
The "it's your turn" email (queued) |
app/Console/Commands/CreateOfficer.php |
php artisan officer:create |
config/services_list.php |
Services, number prefixes, default service minutes |
database/seeders/DatabaseSeeder.php |
Demo officer and realistic sample queues (local only) |
resources/views/board.blade.php |
The TV display, a standalone page |
tests/Feature/ |
QueueTest (core flow) and TimingAndBoardTest (estimates, leaving, board) |
Dockerfile, docker-compose.yml, docker/entrypoint.sh |
Apache image build and first-start setup (env file, key, migrations, caches) |
Services. Edit config/services_list.php. The key is stored in the database, label is shown to people, and prefix starts the queue number.
'visa-application' => ['label' => 'Visa application', 'prefix' => 'VA'],Environment variables (see .env.example):
| Variable | Default | Purpose |
|---|---|---|
APP_TIMEZONE |
Africa/Nairobi |
Times on the dashboard and in "served today" |
QUEUE_DEFAULT_SERVICE_MINUTES |
5 |
Estimate used before a service has history |
MAIL_MAILER |
log |
log writes emails to storage/logs/laravel.log. Set the MAIL_* values for real email |
QUEUE_CONNECTION |
sync |
Use database in production and run php artisan queue:work |
DEMO_DATA |
0 |
Docker only: 1 loads the demo officer and sample queues |
php artisan test
vendor/bin/pint --test| Test file | Covers |
|---|---|
QueueTest |
Joining, validation, per-service numbering, unguessable status links, disabled registration, login, calling the oldest entry, email, completing, mail failures |
TimingAndBoardTest |
called_at / completed_at timestamps, average service time and its fallback, wait estimates, leaving the queue, calling skips people who left, board shows no personal data, dashboard stats, queue lengths on the join form |
GitHub Actions (.github/workflows/tests.yml) runs on every push and pull request:
- PHPUnit on PHP 8.2 and 8.3
- Laravel Pint style check
- Docker: builds the image, starts it with demo data, waits for
/up, then requests/,/boardand/board/json
| Problem | What the app does |
|---|---|
| Anyone could register as an officer | Registration route removed, officers created by command |
Status URL used /status/1, so others' entries could be browsed |
Links use a random UUID token |
| Two applicants could get the same number | Numbers are issued inside a database transaction, sequential per service |
| Two officers could call the same person | The next entry is locked while it is being called |
| A mail error could break "Call next" | Email is queued and failures are logged, not fatal |
| The waiting-room screen is visible to everyone | The board and its JSON only contain queue numbers |
| A fixed "5 minutes per person" is wrong for most services | Each service's estimate comes from its own recent history |
| Polling could overload the server | The JSON endpoints run a handful of indexed COUNT/SELECT queries |
- SMS notifications (Africa's Talking) for applicants without email
- Multiple counters per service, so each officer serves from their own desk
- "Almost your turn" notification when two people are ahead
- Admin screen to manage services and officers
- Daily reports: busiest hours, average wait per service
MIT. See LICENSE.
Mark Kinuthia - github.com/kinuthia-mark




