Key Concepts¶
Understanding these concepts will help you make sense of how Hardhat Flow is built and why it behaves the way it does.
1. Multi-Tenancy¶
Hardhat Flow is a multi-tenant platform. Each company that uses Hardhat Flow is a separate tenant, and every tenant has a completely isolated database. There is no shared data between companies — not users, not bids, not jobs, not invoices, nothing.
Tenant isolation is absolute.
No query, no API call, and no user action can ever access data from another tenant. This is enforced at the middleware and database router level — not just by filtering in application code.
This architecture means:
- Your company's data is yours alone
- A misconfiguration at one tenant cannot leak data to another
- Each tenant's database can be managed, backed up, and restored independently
Platform Admins are the only users who operate across tenants, and they do so through a separate administrative interface.
2. Role-Based Access Control¶
Every user has exactly one role. That role is assigned when the user account is created and determines every permission that user has in the system.
Roles are not additive.
You cannot combine roles. A user is either a Project Manager or an Accounting user — not both. If someone needs capabilities from multiple roles, the Owner or Platform Admin should evaluate which role best fits their responsibilities.
Permissions are enforced at every API endpoint — not just in the user interface. Even if a user somehow bypasses the UI, the server will reject unauthorized requests.
The six roles are:
| Role | Scope |
|---|---|
| Platform Admin | All tenants, system level |
| Owner | Full access within their company |
| Accounting | Financial records only |
| Project Manager | Bids, jobs (assigned), worker coordination |
| Supervisor | Assigned jobs only |
| Badge Worker | Assigned jobs only, read + update |
See Who Uses It for a detailed breakdown and the Permissions Matrix for a full feature grid.
3. Soft Deletes¶
In Hardhat Flow, nothing is ever permanently deleted. When a record is "deleted," it is marked as inactive and hidden from normal views — but it remains in the database.
There is no hard delete anywhere in the system.
This applies to users, bids, jobs, invoices, updates, photos, and all other records.
This design is intentional:
- Audit compliance — you always have a complete history
- Recoverability — records can be restored if something was deleted by mistake
- Legal protection — project records are preserved even if a user account is deactivated
If you need to "remove" a record, use the appropriate status (e.g., cancel a bid or job). Contact a Platform Admin if a record needs to be restored.
4. Immutable Audit Trail¶
Every action in Hardhat Flow is recorded in the Activity Log. This log is append-only — entries are written once and can never be edited or deleted.
The Activity Log cannot be modified by anyone — including Platform Admins.
This is enforced at the data model level, not just by role restrictions.
The Activity Log captures:
- Status changes on bids, jobs, and invoices
- User assignments and reassignments
- Updates posted by field workers
- Payment records
- Flag changes (blocked, priority)
This gives you a complete, defensible record of everything that happened on a project — useful for disputes, audits, and post-project reviews. The Activity Feed is visible on every bid and job detail page to users with appropriate access.
5. The Blocked Flag¶
Any bid or job can be marked as Blocked at any time by a Project Manager or Owner. The blocked flag is independent of status — a job can be In Progress and blocked simultaneously.
When a record is flagged as blocked:
- The flag is visible immediately on the bid or job detail
- An SMS notification is sent asynchronously to the assigned Project Manager and the Owner
- The record remains in its current status — blocking does not pause the workflow automatically
Use the Blocked flag to escalate issues that need attention.
If a job is stalled waiting for materials, permits, or client decisions, marking it as blocked surfaces the issue to leadership without changing the job's operational status.
Clearing the blocked flag also sends an SMS notification so the team knows the issue is resolved.
6. The Priority Flag¶
Any bid or job can be marked as Priority to signal that it requires urgent attention. Like the blocked flag, priority is orthogonal to status and can be set at any time by a Project Manager or Owner.
When a record is flagged as priority:
- A visual indicator appears on the bid or job in all list views
- An SMS notification is sent to the assigned Project Manager and Owner
Use Priority to surface time-sensitive work in busy pipelines.
Priority flags are visible in list and dashboard views, making it easy for Owners and PMs to quickly identify what needs attention first.
Priority and blocked flags can be set independently — a record can be both priority and blocked, or either, or neither.
7. Phone and small screens¶
On a narrow screen or phone, the main sections of the app (Dashboard, Bids, Jobs, Search, and other items your role allows) are listed in the menu you open from the icon at the top left of the screen — not from a bar at the bottom. Tap that icon to move between sections; tap outside the menu or the close control to dismiss it.