Staff Documents — Track contracts, criminal records, health books, and work permits
Upload once, get notified before they expire. Manager-uploaded only (anti social-engineering); staff see their own copies on their phone; expiry watcher pages you 30/14/3 days out.
What is staff document management?
Staff Documents is the compliance layer of the Ordering.Tools Staff module. For each team member you track the documents that prove they're legal to work for you — labour contract + НАП notification, criminal-record certificate (свидетелство за съдимост), health book (здравна книжка), food handler certificate, work permit and residence card for non-EU staff, plus any 'OTHER' free-form documents. Upload the file; set issued / expires dates; mark verified once you've seen the original. The platform alerts you 30 / 14 / 3 days before any document expires.
We deliberately don't auto-pull from BG government APIs (there isn't a public one for criminal records; the ГРАО registry isn't accessible; portal-scraping is a privacy minefield). What we do: track the document the staff member already has. Manager uploads only — staff can't upload their own (anti social-engineering); staff see their copies on their phone in read-only mode. Expiry watcher runs nightly and pages the manager via web-push and email at 30 / 14 / 3 / 0 / +1 day from the expires-at boundary.
Why this is the compliance layer that actually gets used
Manager uploads only (anti social-engineering)
Letting staff upload their own documents is a vector for phishing and forgery. Ordering.Tools requires the manager to upload after seeing the original — the audit log records who uploaded, when, and (when verified) who attested they saw the original. Forged documents get caught at the source.
Staff see their own — read-only
Staff open My Documents on their phone and see what's on file: kind, issue date, expiry date, verification status. They can plan to renew their health book before it expires; they don't need to ask HR every time.
Expiry watcher: 30 / 14 / 3 / 0 / +1
The cron:nightly runner sweeps every document with an expiresAt and surfaces them at the right windows. Manager gets web-push at 30 days out, email at 14 and 3, and a daily reminder until the document is replaced.
Configurable required vs tracked
Per venue, mark which document kinds are 'required' (block scheduling when missing or expired) vs 'tracked' (alert only). A health book is required for kitchen staff in BG; a residence card is tracked but not blocking until expired.
How staff document tracking works
Enable compliance for the venue
Toggle enableStaffCompliance in Staff → Settings. The Documents tab in each staff member's dossier becomes visible; the expiry watcher starts running nightly.
Upload the document
Open the staff dossier → Documents tab → New. Pick the kind (CRIMINAL_RECORD / EMPLOYMENT_CONTRACT / WORK_PERMIT / HEALTH_BOOK / FOOD_HANDLER_CERT / RESIDENCE_CARD / OTHER). Upload the file (PDF or JPG, ≤10 MB, EXIF-stripped server-side). Set issuedAt + expiresAt.
Mark verified
After you've seen the original document in person, click Verified. The system records verifiedById + verifiedAt. From that moment the document is trusted; staff and managers see the green Verified badge.
Renew before expiry
30 days before the expiry, the watcher web-pushes you. Plan the renewal. Upload the new document. The old one becomes part of the audit trail (preserved, not deleted); the new one becomes active.
Staff Documents — feature deep-dive
Document kinds tailored to BG hospitality
The default kind set covers every legal artefact a BG hospitality employer tracks: contract + НАП notification, criminal-record certificate, health book, food handler certificate, work permit, residence card, plus OTHER for anything else.
- Свидетелство за съдимост — the 6-month criminal-record cert
- Трудов договор + Уведомление по чл. 62 ал. 5 — labour contract + НАП notification
- Здравна книжка — annual food-handler health book
- Разрешение за работа + Карта за пребиваване — non-EU work permit + residence card
Manager-only uploads with audit trail
Staff can't upload — the route returns 403. Managers can; the StaffAuditLog records who uploaded, when, what kind, and (when later verified) who verified. Forged or self-uploaded documents are impossible.
- POST /api/admin/staff/{userId}/documents — admin-only
- Staff GET /api/staff/my-documents — read-only access
- Verified flag with verifiedById + verifiedAt for attestation
- Audit trail for every upload, edit, and verification
S3 storage with EXIF stripping
Uploaded files go to AWS S3 with a signed URL. Server-side EXIF strip removes camera GPS and metadata before storage. Files are never indexed by search engines (S3 ACL: private). Signed-URL retrieval keeps access log per request.
- ≤10 MB per file (PDF or JPG)
- Server-side EXIF strip (no camera GPS leaks)
- Private S3 ACL — never crawlable
- Signed URLs with short TTL — no link sharing on Slack
Expiry watcher (cron:nightly)
Every night the watcher sweeps documents with expiresAt and groups them into 30/14/3/0/+1 day buckets. Counts surface in cron logs; web-push + email alerts dispatch via the existing notification pipeline.
- Bucketed alerts — 30/14/3/0/+1 day windows
- Idempotent — re-running on the same day doesn't duplicate notifications
- Manager web-push for time-sensitive alerts (3 days, 0 days)
- Email digest for less-urgent windows (30, 14 days)
Where staff documents save you a fine
Annual health-book renewal
BG food-handler health books renew yearly. The watcher pings the manager 30 days before each kitchen staff member's expiry. The manager schedules the medical visit; the renewed book gets uploaded; old one becomes audit-trail.
New hire onboarding
Day 1 of a new server: take photos of their criminal record, contract, and health book. Upload all three from your phone in 90 seconds. Mark verified. The system tracks renewal dates for you forever after.
Surprise inspection
Inspector shows up Friday lunch. 'Where are your staff health books?' Open Staff → Members, click any kitchen staff member, Documents tab. Every health book is on file with verification dates. Inspection takes 4 minutes instead of 40.
Non-EU staff residence-card renewal
A non-EU server's residence card expires in 60 days. The watcher pings you at 30 days; you remind the staff member to renew; they bring the new card in 21 days; you upload, verify, mark active. No surprise legal exposure.
Required-document blocking
Mark health book as required for KITCHEN role. A kitchen hire whose health book is missing or expired can't be scheduled (the rota grid surfaces a warning). The block prevents accidental compliance violations at scheduling time.
Staff self-service renewal
A staff member opens My Documents, sees their criminal record expires in 25 days, plans the trip to court, brings the new certificate in. Manager uploads, marks verified. No HR escalation, no missed expiry.
Compliance tracking that respects staff dignity and HR reality
Most 'compliance' software for restaurants is theatre — it asks staff to upload their own documents, which means an angry employee can upload a forged contract and the system happily accepts it. Or it tries to integrate with government APIs that don't exist (no public BG criminal-record API; ГРАО isn't accessible; courts have no write API). Ordering.Tools picks a deliberate middle path: track the document the staff member already has, manager-uploads only, expiry watcher runs nightly, audit trail records every upload and verification. The result is compliance that actually gets used because it doesn't ask anyone to do something fake.
Why manager-only uploads matter
If staff can upload their own documents, you have no defence against forgery. A waiter who's been fired for theft can't rejoin under a different name with a self-uploaded criminal record certificate that's actually a Photoshopped image of someone else's. Manager-only uploads with the verified flag means there's always a real person attesting they saw the original. That attestation is timestamped and auditable. If a regulator later questions a hire, the audit trail names the manager who verified the document and when.
Why we don't auto-pull from BG government APIs
There's no Checkr-equivalent for BG. BG courts don't expose a public criminal-record API. The ГРАО registry isn't accessible to private parties. The НОИ portal requires staff member SSO consent + electronic signature for every read. Portal-scraping is fragile and a privacy minefield. We help track the document the staff member already has — that's the realistic, ethical, sustainable answer. Adding a fake API integration that breaks every six months when the government redesigns its portal is worse than not having one.
The 30/14/3/0/+1 cadence
Why these specific intervals? 30 days is the lead time most renewals need (health-book medical visit, court appearance for criminal record). 14 days is the 'getting close' reminder. 3 days is 'now or never' — the manager pulls the staff member off rota if they don't have the renewal scheduled. 0 days is the day-of alert. +1 day is the post-expiry trail — the document is now expired, the staff member shouldn't be working in roles that require it, the manager has been notified five times. The cadence isn't arbitrary; it matches BG regulatory renewal timelines and gives every party fair warning.
Stop tracking compliance in a spreadsheet
Upload, track, get notified. Manager-only uploads, staff-readable, expiry-watched. Premium feature, included in Staff Management.