# AmChex administration system specification

Version 1.0 - 30 September 2026. Public-safe implementation specification for a future real AmChex business, presented as a worked example for Know Everything, Do Anything. The current showcase and enquiry inbox use fictional enquiries only. This describes a future system. It does not claim that these capabilities are currently live. It contains no customer records, credentials or production configuration.

## 1. Purpose and delivery boundary

AmChex is a worked business example for UK recruitment agencies planning US construction placements. If launched as a real business, its administration system must turn an enquiry into an owned, evidence-backed project assessment, then support a controlled pilot with named specialist partners. It must make unresolved responsibilities visible and prevent an administrative checklist from being mistaken for legal approval. Every public showcase form must tell visitors to use fictional details and describe submissions as demonstrations. Real sales collection requires a separate launch decision, verified contact details and an appropriate privacy notice.

The immediate website release has a small owner inbox for fictional enquiries. The next-stage system in this specification extends that inbox on the site's dedicated Convex backend, with individual authenticated accounts and server-enforced roles. The public site remains the marketing and enquiry surface. Internal workflows sit behind authentication at `/admin`. Use the existing site styling, accessible form components and backend conventions. Do not migrate records to another platform or add a second CRM. Segregate demonstration records from any future production environment, and do not convert them into sales leads.

Included: enquiries, agencies and contacts, partner due diligence, capability coverage, projects, evidence references, tasks, deadlines, approval records, research review, finance handoff and an audit history. Excluded: immigration adjudication, legal advice, payroll calculation, tax filing, worker payments, automated hiring decisions, full applicant tracking and document storage for passports or Social Security numbers. A system status is an internal workflow decision and never a guarantee of lawful deployment.

Success means each active enquiry and project has an accountable owner, next action and review date. Every pilot has written partner acceptance for its actual scope. The system can show why a project is blocked, who can resolve it, and the evidence behind each readiness decision.

## 2. Roles and permission model

Use Clerk for named, invite-only user accounts and its documented Convex token integration. Configure separate development and production instances. Keep the existing frontend framework, using the appropriate Clerk client SDK and Convex authentication integration. Verify tokens on the server. Store roles in the backend, keyed to the immutable authenticated subject. Do not accept a role, account identifier or owner identifier supplied by the browser as authority. Provision the first Owner through an audited deployment administration process. Disable the shared owner-password mechanism when individual authentication launches and invalidate its sessions. This is a next-stage design choice, not an instruction to create a Clerk account or change the current demonstration.

| Action | Owner | Operations | Editor |
| --- | --- | --- | --- |
| Read operational enquiries, contacts and projects | Yes | Yes | No |
| Create and update enquiries, contacts, tasks and project drafts | Yes | Yes | No |
| Record partner evidence and propose readiness checks | Yes | Yes | No |
| Approve a partner, commercial handoff or project release | Yes | No | No |
| Maintain research drafts and public resources | Yes | Read operationally relevant research | Yes |
| Publish research/content changes | Yes | No | Submit for approval |
| Export personal/contact or commercial data | Yes, audited | No bulk export | No |
| Assign roles, disable accounts, archive records, handle deletion | Yes | No | No |

Operations users initially share access to all operational records within AmChex. Introduce tenant isolation only if an external agency portal is separately commissioned. No agency, worker or delivery partner receives admin access in this phase. Editors see research and content only, including a redacted source register. Hiding a navigation item is not access control: every query and mutation must enforce its permissions.

Require reauthentication for account/role changes and bulk exports. Log sign-in failures and apply provider-level rate limits. Use multi-factor authentication for Owner and Operations accounts. On role removal or account disablement, reject access on the next backend request and revoke active sessions where supported. The last active Owner cannot remove their own Owner role.

## 3. Records and data contracts

Use opaque Convex IDs. Store times in UTC and display in Europe/London by default, with worksite time zones shown next to payroll and site deadlines. Store money as integer minor units with an ISO currency, never floating-point money. Preserve original and normalised business email values for display and matching. Required common fields are `createdAt`, `updatedAt`, `createdBy`, `updatedBy`, `version` and, where applicable, `archivedAt`. All mutations require an expected record version and reject stale writes with a conflict message rather than overwriting another user's work.

| Entity | Minimum data and relationships |
| --- | --- |
| Enquiry | Submission timestamp, name, work email, agency name, optional phone, role, intended US state, trade summary, approximate headcount, indicative dates, free-text message, privacy-notice version, source, status, owner, nextActionAt, optional agency/contact/project IDs. Retain an immutable original submission. |
| Agency | Trading and legal names, country, company registration reference where supplied, website, business address when needed for contracts, status, owner, contact IDs and due-diligence summary. |
| Contact | Name, work email, optional business phone, agency ID, role, preferred contact method, communication restriction and last-contact date. Marketing permission and operational contact basis are separate fields. |
| Partner | Legal entity and trading names, service type, jurisdictions, relationship owner, review status, evidence references, reviewer, review date and nextReviewAt. Public marketing claims are separate from confirmed contractual coverage. |
| Capability | Partner ID, country/state, duties/trade description, workers' compensation class code if confirmed, worksite/hazard restrictions, employment model, immigration-support scope, funding scope, accepted contracting chain, effective/expiry dates, evidence IDs and verification status. Empty means unknown, never covered. |
| Project | Agency ID, commercial client and host-site identities, state/address/time zone, duties, dates, planned cohort count, broad nationality/authorization categories only where necessary for assessment, owner, partner IDs, status, nextActionAt, risk summary, signed-scope reference and readiness-check IDs. |
| Responsibility | Project ID, responsibility type, named organisation/contact, acceptance state, evidence reference, acceptedAt and expiry. Types include legal employer, immigration petitioner, immigration counsel, payroll operator, tax filer, insurance provider, site supervisor, safety lead, travel/accommodation coordinator and invoice debtor. |
| Readiness check | Project ID, check type, status, owner, evidence IDs, checkedAt, validUntil, reviewer and reason. States: unknown, in progress, satisfied, blocked, not applicable. Not applicable requires an Owner decision and reason. |
| Evidence reference | Title, source type, source URL or approved secure repository reference, publisher, scope, obtained/reviewed dates, expiry, verification state, reviewer, checksum where available, and short factual summary. Do not store confidential source documents in public website storage. |
| Task | Related record type/ID, title, assignee, priority, dueAt, status, dependency IDs, completion reason and completedAt. Status: open, in progress, blocked, done, cancelled. |
| Research item | Topic, state if relevant, primary URL, publisher, lastVerifiedAt, nextReviewAt, extracted factual summary, applicability/limitations, reviewer, status and supersededBy. Status: draft, in review, approved, expired, superseded. |
| Approval | Target ID and version, type, requestedBy/At, decision maker/time, decision, evidence snapshot and reason. Decisions: pending, approved, rejected, withdrawn, expired. |
| Finance handoff | Project/version, contracting entities, debtor, currencies, itemised commercial assumptions, written quote references, expected payroll/client dates, funding approval reference/limit/expiry, deposits, credit status, approver and export history. |
| Audit event | Actor subject, action, record ID/type, timestamp, changed-field names, minimal before/after values, reason and correlation ID. Exclude credentials, sensitive documents and raw form text from security logs. |

Partners may have multiple legal entities and capabilities. Approval of a partner's identity does not approve every capability. Each project must match current, verified coverage for its state, duties, hazard profile, employment/immigration arrangement and contracting chain. Store the exact evidence used for approval so later supplier-page changes cannot silently alter the original decision.

## 4. Workflow and screens

### Enquiries and CRM

The public form calls the existing enquiry intake endpoint. Validate on the server, limit field lengths, reject unexpected fields, use a honeypot and rate limiting, and show a neutral success response. Do not echo submissions into URLs, analytics or public error messages. The endpoint accepts an idempotency key so a retry cannot create another enquiry. On success it creates the enquiry and an owner-triage task in the same transaction.

Enquiry states are new, reviewing, qualified, on hold, converted, declined and spam. Only Operations or Owner may change them. Moving into on hold or declined requires a reason. Conversion is an explicit action that links or creates an agency/contact and a project in draft, without deleting the original enquiry. Show probable duplicates using normalised email plus agency and recent submissions. Never automatically merge people. Owner merges with a preview and preserves all original submissions and audit links.

The inbox defaults to new/reviewing enquiries sorted by oldest unowned then next action. It shows date, agency, contact, project summary, owner, status and next action. Detail pages show original submission, internal notes, tasks and history. Internal notes are plain text with length limits, not executable HTML. Search uses indexed fields and paginated server queries. No full-table data dump to the browser.

Operational contact about an enquiry is distinct from marketing. Record a manual contact note after a person sends correspondence through the approved business mailbox. V1 does not send email, social messages or automated follow-ups. Future sending requires an explicit product change, consent/lawful-basis review, suppression lists, provider integration and audit controls.

### Partners and coverage

Partner states are candidate, evidence requested, under review, approved, suspended and rejected. Supplier claims start unverified. Approval requires legal-entity identity, actual scope acceptance, service agreement review, insurance evidence and a current escalation contact. A signed agreement and insurer evidence outrank a marketing page. Owner alone approves or suspends a partner.

Coverage view filters by state, trade/hazard and service, with confirmed, unconfirmed, restricted and expired results. A project can reference a candidate during exploration, but cannot receive release approval through unconfirmed capability. Changing a relevant restriction, expiring insurance or suspending a partner marks dependent projects for review and opens a blocking task. It never silently swaps suppliers.

### Projects and readiness

Project states are draft, assessing, blocked, ready for approval, approved for mobilisation, active, on hold, closing, closed and cancelled. Assessing can move to blocked and back. Ready for approval requires all mandatory checks satisfied or expressly marked not applicable. Only Owner can approve mobilisation or mark a project active. Any material change after approval invalidates the previous approval and returns the project to assessing or on hold.

Material changes include worksite/state, duties/hazards, employer, immigration petitioner or route, contracted parties, dates, rates, cohort composition affecting eligibility, insurance or funding. For active projects, these changes create a stop/review task and notify the Owner in the dashboard. The application must never infer that existing work authorization covers an altered placement.

Mandatory readiness checks: client/agency identity and contract chain; role and site definition; written immigration assessment and authorization verification owner; named legal employer/petitioner/counsel; current partner acceptance; applicable registrations/licences; payroll and tax responsibility; insurance and safety allocation; worker terms and welfare arrangements; funding/credit and signed costs; incident/escalation contacts; authorised release. Evidence may be an external counsel or partner confirmation. The application must not decide a visa category, calculate tax or certify safety.

The project page shows an explicit blocking list, responsibility matrix, dates, tasks, evidence and approvals. A green checklist means internal evidence is current, and must be labelled “Internal readiness review complete”. Use “Approved for mobilisation by [name/date]” only after the Owner decision. Avoid “compliant”, “visa approved” or “ready to work” as blanket system labels.

### Tasks, research and approvals

Dashboard queues: unowned enquiries, overdue actions, blocked projects, expiring partner evidence, pending Owner decisions and research due for review. Default enquiry-triage target is two UK business days. It is an internal operating target, not a public SLA. Calculate business days using a maintained England and Wales bank-holiday calendar. Store the resulting timestamp to keep deadlines reproducible.

A daily scheduled backend job creates reminder events and dashboard counts without contacting external people. Deduplicate on task ID and due-date version. Retry transient failures and retain the last successful run time for an Owner health indicator. Do not rely on scheduled jobs to enforce expiry: queries and approval mutations must check current validity synchronously.

Research is reviewed at least every 90 days, earlier for explicitly time-sensitive rules or announced changes. The Owner may set a shorter date. Expired research remains readable with a warning, but cannot support a fresh approval. Editors propose revisions, Owner publishes. A source failure creates “needs verification”; it does not mean the law changed. Preserve old versions and effective dates.

Approval requests freeze target version and evidence references. A later edit marks the pending request stale. Approval mutations confirm actor role, target version, evidence validity and dependencies atomically. Rejection needs a reason. Owner may withdraw an approval with a reason, and the change creates downstream tasks. There is no “force approve” bypass for a blocked mandatory check.

### Finance handoff

Finance records organise externally calculated and approved figures. They do not calculate statutory payroll or initiate funds movement. Capture wage and overtime assumptions, employer burdens from partner quotes, service fees, immigration/mobilisation costs, expenses, FX assumption date, credit terms, client collections, partner pay dates and funding limits. Distinguish AmChex revenue, pass-through costs, contribution and working-capital need.

Owner exports a versioned CSV and human-readable summary for the accountant and delivery partner. Include evidence/quote references, approval identity and date. Escape CSV cells starting with formula characters to prevent spreadsheet execution. Exports exclude unnecessary personal data. Never add bank accounts, payment credentials or worker tax identifiers to this handoff.

## 5. Backend interfaces and integrity

Implement named Convex queries and mutations grouped by enquiries, agencies, contacts, partners, projects, tasks, research, approvals, finance and audit. Each accepts validated IDs, bounded strings and explicit enums. Do not expose generic “update any field” mutations. Server-derived actor/time/audit fields cannot be client controlled.

Minimum operations: `enquiries.list/get/assign/changeStatus/convert`; `agencies.list/get/create/update`; `contacts.create/update`; `partners.list/get/update/requestReview/decide`; `capabilities.upsert/expire`; `projects.list/get/create/updateScope/changeStatus`; `readiness.update/requestApproval`; `responsibilities.assign/recordAcceptance`; `tasks.list/create/update/complete`; `research.list/createRevision/submit/publish`; `approvals.request/decide/withdraw`; `finance.update/requestApproval/export`; `audit.listForRecord`. Public intake remains the sole unauthenticated write surface. Resource downloads and published research are read-only public content.

Return stable error codes for unauthenticated, forbidden, validation, not found, conflict, dependency blocked and evidence expired. UI messages explain the corrective action without exposing other records. Log correlation IDs for unexpected errors. A successful mutation includes updated record version and next required action. Use transactions for conversion, approval, state changes and their audit/task updates.

Indexes must support status/owner/nextActionAt queues, agency contacts, partner capabilities by state/status, project tasks, evidence expiry, research nextReviewAt and audit record/time. Use cursor pagination with a maximum page size of 50. Search must respect permissions. Optimistic UI is suitable for simple task text changes, but approval and release actions wait for server confirmation.

## 6. Data handling and recovery

Use business-contact information and project-level counts during initial assessment. Do not request passports, visa scans, dates of birth, Social Security numbers, medical records, criminal history, bank details or individual immigration case files. Sensitive worker records belong in the selected specialist's approved secure system. The admin system stores a case reference and named verification owner only. If a user enters sensitive material accidentally, Owner can redact it through an audited action while preserving a minimal reason.

Before launch, the Owner and privacy adviser approve a retention schedule and publish the matching privacy notice. Product default: review inactive unconverted enquiries after 12 months for deletion/anonymisation. Contracted project records follow the approved jurisdiction-specific schedule; do not invent a universal legal retention period. Suppression records retain only what is necessary to honour contact restrictions. Provide a subject-access/deletion request workflow with identity verification outside the public form and a legal-hold check before deletion.

Keep secrets in deployment configuration, never source files or the browser. Public download copies must not include private records. Maintain environment separation, least-privilege deployment access, dependency updates and encrypted transport. Log access/export/deletion/security events. Back up data using the supported Convex export/backup process and test restoration into a non-production deployment before operational launch and after material schema changes. Record recovery owner and a target recovery time of one business day as an internal objective pending provider validation.

## 7. Phased implementation and acceptance

### Phase 1 - replace the small owner inbox

Introduce individual authentication, roles, server permission checks, enquiry ownership/statuses, tasks and immutable audit events. Migrate existing enquiries preserving original timestamps and content. Import shared-password inbox records only, never password/session values. Run a count and field comparison, test the new access path, then disable old access. Acceptance: existing enquiries remain available, unauthenticated requests reveal no records, Editor cannot read enquiries, duplicate submissions are idempotent, stale concurrent edits return conflicts, and disabled users lose access.

### Phase 2 - operational readiness

Add agencies, contacts, partner/capability records, projects, responsibility assignments, evidence and approval gates. Acceptance: a candidate partner cannot support release; unknown coverage blocks approval; expired insurance blocks approval even if the reminder job has not run; a role/site/employer change invalidates approval; a suspended partner flags all active affected projects; no user can skip mandatory checks through direct API calls; only Owner can approve, and an audit entry records the exact version/evidence.

### Phase 3 - research and finance handoff

Add source review queues, content approval, finance assumptions, exports and recovery procedures. Acceptance: stale research cannot support a fresh decision; failed source checks create review tasks without replacing prior evidence; Editors cannot publish without Owner action; CSV export is safe against formula injection; exports include approved versions only; money/currency remain intact; backups restore into a test deployment with relationships preserved.

### Before using the system for a live pilot

Run an end-to-end synthetic case from public enquiry to closed project, with fictional business contacts clearly labelled as test data. Include late evidence, conflicting edits, withdrawn approval, client cancellation, data-redaction request and missed payroll escalation. Verify keyboard navigation, focus handling, error summaries, mobile inbox usability and understandable empty states. Confirm no test record, secret or personal data appears in public resources. Owner signs the acceptance record. Deploy a small internal pilot, review audit/queue accuracy weekly for four weeks, and expand only after defects affecting permissions, release gates or evidence have closed.

## 8. References and interpretation

This specification translates the proposed AmChex operating model into software requirements. It is not an instruction to provide regulated services without qualified review. Primary starting points: [USCIS Form I-9](https://www.uscis.gov/i-9), [IRS payroll and third-party payers](https://www.irs.gov/businesses/small-businesses-self-employed/outsourcing-payroll-and-third-party-payers), [OSHA temporary workers](https://www.osha.gov/temporaryworkers), [ICO data minimisation](https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/data-protection-principles/a-guide-to-the-data-protection-principles/data-minimisation/) and [Convex Clerk integration](https://docs.convex.dev/auth/clerk). Validate current applicability with the responsible adviser and the actual worksite/contracting arrangements.