CivicPlexus User Guide

Welcome to CivicPlexus, the HRIS built for city and county government. This guide walks every role — Admins, HR, Hiring Managers, Supervisors, IT, and Employees — through first-time setup and daily operations. No technical background required.

CivicPlexus is one system from req to retire: recruiting, onboarding, core HR & records, payroll & benefits, performance & development, and public-sector compliance (FLSA, EEO‑4, TCOLE, TMRS, FMLA, new‑hire reporting). Onboarding is one module of many.

Screenshots referenced as ![placeholder] are intentionally blank. Drop your own PNGs into docs/img/ before printing or sharing.

1. Concepts at a glance

2. First-time setup (Admin — do this once)

2.1 Claim the admin role

1. Visit the app, click Create account, sign up with your work email.
2. The first signup defaults to the candidate role. Promote yourself by running this SQL in the database SQL editor (Lovable Cloud users: Cloud → Database → SQL editor; self-hosters: Supabase Studio → SQL):

   INSERT INTO public.user_roles (user_id, role)
   SELECT id, 'hr_admin' FROM auth.users WHERE email = 'you@city.gov';
   

3. Sign out and back in. You should now see People, Recruiting, Pay, Performance, Compliance, and Admin groups in the sidebar.

2.2 Configure the organization (Admin → Settings)

• Org profile: name, EIN, mailing address, phone.
• Branding: primary + accent colors (writes to CSS variables, applies on next reload).
• Retention policy (JSON): how long to keep each document kind. Sample:

  { "i9": 3, "w4": 4, "policy_ack": 7, "screening": 5, "training_cert": 7, "payroll": 7 }
  

• Email sender: EMAIL_FROM address and verified domain (see Self-Hosting Guide §9).
• SSO metadata URL: paste your Entra/Okta SAML metadata URL. Apply via support after saving.
• Google auth: enable in Cloud → Auth → Providers if you want one-click sign-in.

2.3 Invite your team

Ask each teammate to sign up, then assign their role:

INSERT INTO public.user_roles (user_id, role)
SELECT id, 'hiring_manager' FROM auth.users WHERE email = 'manager@city.gov';

Valid roles: hr_admin, hiring_manager, supervisor, it_admin, manager, employee, candidate.

2.4 Set up payroll plumbing (HR + Finance)

1. Pay Calendars — define your pay frequency (weekly, biweekly, semimonthly, monthly) and period boundaries.
2. Pay Groups — group employees by who they're paid alongside (e.g., General, Police, Fire, Council).
3. Pay Periods — auto-generated from each calendar; verify the next 12 months look correct.
4. Payroll Export Profiles — pick the format your provider expects (CSV columns, fixed-width, etc.).

2.5 Set up the salary structure

1. Comp Grades — create grades with min / mid / max.
2. Comp Market — import or paste market ranges per grade per benchmark source.
3. Positions — assign every position a grade and an FLSA class (exempt / non-exempt).

2.6 Review seeded worker types and templates

1. Worker Types — confirm the list matches what your municipality hires (Office/Admin, Field Staff, Public Safety, Temporary/Seasonal, Contractor/Vendor, Volunteer, Elected/Appointee).
2. Templates — every worker type ships with a default onboarding template covering I-9, W-4, OSHA, fingerprinting, DOT/CDL, equipment, training, and provisioning as relevant.
3. To customize: open a template, Clone, edit task list, set due_offset_days and assignee role (employee, hr, manager, it), then Publish.

3. Recruit & Hire (ATS)

3.1 Hire requests

Supervisors and hiring managers file a Hire Request with proposed name, title, department, worker type, start date, and the provisioning kinds the new hire will need. HR reviews and either Activates (starts onboarding) or Rejects (cleans up the draft employee).

3.2 Requisitions and the careers site

• Jobs → New Requisition: title, department, position, pay range, posting copy, internal-only flag.
• Posted requisitions show up on the Careers page (/careers) and, for internal candidates, on Internal Careers.
• Applications come in through /careers/<slug>/apply. Resumes are uploaded to private storage; PDF resumes are parsed for HR search.

3.3 Screenings, interviews, offers

• Screenings — order background / fingerprint / drug / MVR / credit checks, attach results when they come back.
• Interviews — schedule, capture Interview Feedback from each panelist with a structured rubric.
• Live panel rooms — when LiveKit is configured (see Self-Hosting Guide → LiveKit), the interview detail page exposes a Join room action that opens a recorded, watermarked, two-party-consent video room for the hiring panel. Async candidate "two-take" video responses always work; live rooms are an optional add-on and the page shows an in-app setup banner to HR when credentials are missing.
• Offers — generate from a doc template, send via the tokenized Offer Portal (/offer/<token>). Candidate accepts or declines online; HR is notified.
• Candidate messaging — send and receive messages from the candidate portal (/candidate/<token>) without sharing email threads.

3.4 Voluntary self-identification

Public applications include EEO self-ID (gender, race/ethnicity, veteran status, disability) — fully optional, encrypted at rest, only visible in aggregated EEO reports.

4. Onboard & Provision

4.1 Add an employee

1. Employees → New Employee (or approve a Hire Request).
2. Enter name, email, start date, department, worker type, position.
3. The system creates an Onboarding Instance and generates every task from the worker type's default template. Email the preboarding link.

4.2 Preboarding portal (employee view)

The new hire signs in and sees their checklist: forms to fill, documents to upload, policies to sign, training to complete. Progress percentage updates live.

4.3 Forms library and signatures

• Build forms in Forms Library. Each form has a key (used by template tasks), a JSON schema, and an optional signature requirement.
• Signed submissions write to Signatures with timestamp + signer name (E-SIGN compliant).

4.4 Documents

• Reviewers see uploads in Documents with status (Pending, Approved, Rejected) and a preview pane.
• Approve, reject with reason, or request re-upload. All actions write to Audit Log.

4.5 Doc templates and generation

• Doc Templates holds merge templates (offer letters, PAFs, separation letters, certificates).
• Docs Generator renders a template against an employee + variables and stores the resulting PDF in Documents.

4.6 IT provisioning

• IT Provisioning is a kanban: Requested → In Progress → Completed → Rejected.
• Auto-populated from template tasks tagged provisioning (email account, badge, laptop, software licenses, system access).

4.7 Equipment & PPE

• Maintain the Equipment Catalog (SKU, sizes, cost center).
• Capture PPE sizing per employee.
• Track Issuance with issued/returned dates and condition.

4.8 New-hire batches and reporting

• New Hire Batches groups onboardings for orientation cohorts.
• New Hire Reports queues each activation for state new-hire reporting (TWC in Texas) and lets you export the file.

5. Core HR & Records

5.1 Employees

The central record: contact info, employment status, manager, position, worker type, dates, sensitive identifiers (encrypted), and links to every other module.

5.2 Positions

Budgeted seats with title, department, grade, FLSA class, reports-to. Vacancies are visible to recruiting.

5.3 Personnel Action Forms (PAFs)

• PAF → New: pick the action type (promotion, transfer, pay change, status change, separation), the employee, and the effective date.
• The PAF runs through an Approval Chain (stages with role-based approvers); each step is auditable.
• On final approval, the underlying employee/position/comp record updates.

5.4 My HR (self-service)

Employees see their own profile, paystubs, documents, time-off balance, assigned training, pending policies, and PAFs that affect them.

5.5 Personnel record history (timeline)

Every employee profile has a unified Personnel record history tab that merges hires, status changes, compensation, PAF activity, reviews, training, provisioning, grievances, and audit events into one chronological view.

• Filter by category, export the visible rows to CSV.
• Attachments for an event — PAF supporting documents, training proof of completion, certification PDFs — appear as paperclip chips beneath the event. Click a chip to open the file in a new tab via a short-lived signed URL (5-minute expiry, scoped to that employee).
• Files marked sensitive show a lock icon. Access is limited to HR admins and the employee themselves; every open is auditable.
• Employees see the same timeline for their own record under My HR → Personnel history.

6. Pay & Benefits

6.1 Comp cycles

1. Comp Cycles → New: name, period, budget %, eligibility filter (departments, worker types).
2. Opening the cycle seeds every eligible employee with a recommended merit % derived from their latest review rating.
3. Managers enter recommendations; HR runs Calibration (distribution by department, rating, gender pay-gap check).
4. Approve → writes new employee_comp rows with the effective date.

6.2 Payroll runs

1. Payroll → New Run: pick the pay period and pay group.
2. The system pulls each employee's current employee_comp, hours, and one-time pay items into Payroll Run Lines.
3. Review, lock, and Export using your configured profile. The file lands in the payroll-exports storage bucket.

6.3 Benefits hand-off

• Mark eligibility, set enrollment window, attach Dependents (DOB, SSN, relationship).
• Generate a hand-off packet for the carrier; carrier callbacks land at /api/public/hooks/benefits-callback (HMAC-signed).

6.4 Timekeeping

• Timekeeping (/timekeeping) is the daily clock-in/out surface. Non-exempt employees punch in and out; weekly totals show straight, overtime, and comp-time hours.
• Exempt employees set a static weekly schedule (the "My weekly schedule" editor); hours logged beyond that schedule bank as 1.0× straight comp time.
• Time policies (HR admin) control OT multipliers, comp-time caps, and rounding.
• Managers approve timesheets from the same page; approvals flow into the payroll run.
• Works offline through the PWA shell (§16) — punches queue locally and sync when the device reconnects.

6.5 Public safety shift patterns

• Shift Patterns (/shift-patterns) defines multi-week rotations: 24/48, Kelly, Pitman, Berkeley, custom.
• Each pattern carries an FLSA 207(k) work period (e.g., 28 days / 212 hours for fire; 7 days / 53 hours weekly equivalent) so compute_timesheet calculates OT against the right threshold, not the 40-hour default.
• Assign patterns to fire/police/EMT employees; their timesheets and comp-time accruals follow the rotation automatically.

6.6 Payroll export profiles

• Payroll → Profiles (/payroll/profiles) holds vendor-specific export templates: Tyler Munis, BS&A, ADP, Paycom, generic CSV.
• Map your payroll fields once; every locked run can be previewed and exported using the chosen profile.

6.7 FTE budget control

• HR + Finance (/hr-finance) tracks department FTE budgets per fiscal year.
• The requisition wizard calls checkPositionBudget before saving and blocks any draft that exceeds remaining headroom unless an HR admin checks the override box (logged to the audit trail).

7. Perform & Develop

7.1 Goals and cascades

• Goals: individual objectives with progress, weight, due date, and optional parent goal. Progress on children rolls up to the parent automatically.
• Cascades (/cascades): org-wide directives published from leadership; teams respond with status updates, and an AI rollup summarizes department-level themes for HR. See the dedicated Cascades user manual PDF for full workflow.

7.2 Review cycles

1. Review Cycles → New: period, eligibility, template, due dates for self / manager / signature.
2. Opening the cycle creates Performance Reviews for every eligible employee and notifies them and their manager.
3. Calibration view lets HR compare ratings across departments and surface outliers; rating changes are logged.
4. Both parties sign; finalized reviews lock and feed the next comp cycle.

7.3 1:1s

Manager and report share an agenda template, take running notes (private to the manager + shared), and capture action items that surface on each other's home pages until done. AI session summaries feed directly into the employee's next annual review draft. See the dedicated 1-on-1 user manual PDF for full workflow.

HR admins edit the manager + employee question sets in 1-on-1 Templates (/one-on-one-templates): clone, edit prompts, publish. Live meetings pick up the next published version.

7.4 Training & certifications

• Assign Courses (one-off or recurring) to employees or to whole worker types.
• Employee Training tracks status, score, evidence upload, and completion.
• Completing a course can issue a Certification with an expiry; Expiry tracker color-codes 30/60/90 days out.
• Transcript prints a full per-employee training history.
• LMS Imports (/lms-imports) ingests completions from external LMSs and maps eligible courses into TCOLE continuing-education credits. Two modes:
  • Manual upload — CSV of completions (employee identifier, course code, completion date, score, evidence URL).
  • Connections (HR admin only) — connect Chamilo, Moodle, or Forma LMS with a base URL and API token. Test the connection, run a sync on demand, or let the built-in pg_cron job auto-sync hourly. Each sync appears in the Sync history panel with rows fetched, matched, applied, and any errors. Tokens are stored as project secrets (LMS_<id>_TOKEN) — the connection form shows the exact secret name after saving.

8. Comply & Govern

8.1 Policies

• Policies page: create with title, body (Markdown supported), effective date, and re-acknowledgment cadence in months.
• Publishing a new version triggers a re-ack Policy Campaign for everyone who previously signed.
• Scroll-to-bottom is required before the signature pad activates.

8.2 FLSA audit

• FLSA Audit lists every position with current exemption class, the last duties-test review, and whether a re-review is due.
• Record a review with decision (exempt / non-exempt / needs review), exemption basis, duties notes, and next review date.

8.3 EEO snapshot

• EEO Snapshot generates a workforce snapshot as of a chosen date, broken down by department and full-time / part-time. Use it to build EEO-4 filings.

8.4 TCOLE (Texas peace officers)

• TCOLE Licences stores PID, licence number, level, issue/expiry.
• TCOLE Completions tracks continuing-education hours by reporting cycle.

8.5 TMRS (Texas Municipal Retirement)

• TMRS Enrollments captures plan, contribution %, vesting.
• TMRS Monthly Files generates the upload TMRS expects each period.

8.6 FMLA cases

Track each leave-of-absence case: dates, hours used vs entitlement, certification status, intermittent vs continuous, return-to-work date.

8.7 Grievances

• Grievances → New: intake form captures complainant, respondent, category, narrative, and confidentiality preference.
• HR assigns an investigator; Grievance Tasks drive the investigation; Grievance Events are a full audit timeline.
• Resolution sets the outcome and notifies the parties.

8.8 OSHA 300 / 300A

• OSHA (/osha) logs workplace incidents, classifies outcomes (death, days away, restricted/transfer, other recordable), and tracks days away / restricted.
• The 300A summary is generated per calendar year for posting and electronic submission.

8.9 Union contracts (CBA)

• CBA (/cba) stores collective bargaining agreements, effective dates, and key terms.
• Surface relevant clauses on PAFs and comp cycles so HR enforces step-and-grade rules correctly.

8.8 Audit log

Filter by actor, entity, date range. Read-only. Retain forever; never delete.

8.9 Reports

Pre-built reports: time-to-hire, time-to-fill, headcount by department, turnover, training compliance %, policy ack %, I-9 compliance %, payroll variance. Every report has an Export CSV button.

9. Roles & permissions

Roles live in public.user_roles. The private.has_role(uid, role) security-definer function backs every RLS policy.

Team-scoped access (Cross-Functional Teams)

Cross-functional teams (/teams) use membership-based access rather than roles:

RLS is enforced by two security-definer helpers: can_view_team(team_id, uid) (member or hr_admin) and can_manage_team(team_id, uid) (lead/co-lead or hr_admin). Non-members cannot see or query the team.

10. Operating cadence

11. Notifications

• In-app bell shows unread count.
• Email delivery uses your configured Resend / SES / SendGrid domain (see Self-Hosting Guide §9).
• Overdue reminders fire daily via pg_cron hitting /api/public/hooks/reminders with a shared secret.

12. Offboarding & rehire

1. Offboarding → New Separation. Pick employee, last day, reason.
2. The system runs the offboarding template: equipment return, access revocation, COBRA notice, final pay, exit interview.
3. Mark rehire_eligible true/false.
4. To rehire: open the former record, Clone Onboarding, optionally skip tasks completed before.

13. Troubleshooting

Support escalation template

Subject: CivicPlexus issue — <one-line summary>
Environment: <production / staging>
User affected: <email + role>
What I expected: ...
What happened: ...
Steps to reproduce: 1) ... 2) ...
Audit log timestamp: <UTC>
Screenshot: attached

14. Appendix

Accessibility

• All interactive elements are keyboard-reachable. Tab cycles, Enter/Space activates.
• Color contrast meets WCAG 2.1 AA.
• Forms support screen readers; labels are always present.

Mobile

The app is responsive down to 360px. Field crews and new hires can complete preboarding, sign policies, and submit time on a phone.

Glossary

See §1.

15. Demo Walkthrough

Sign in as demo.purpose@testingaccount.test (password Demo, 1234). A banner appears with a 24-hour countdown and a "Start tour" launcher. Every change you make is reverted automatically when the timer hits zero, or immediately via Reset now.

The guided tour mirrors the in-app overlay. Each stop names the route, what to look at, and an optional "Try this" action.

1. Dashboard (/dashboard) — KPIs, recent activity, and pending approvals. Try: scan the cards to see live counts from seeded demo data.
2. Employees (/employees) — directory with org, status, and supervisor chain. Try: open any employee for their full record, leave, and assignments.
3. Employee profile (/employees/{id}) — full record, contact info, photo, transcript link, and HR-only ID badge controls. Try: HR can upload a photo, pick a template, and click Generate badge PDF to print a CR80 badge.
4. Org Chart (/org-chart) — photo-driven hierarchy from manager_id, color-coded by department, with search, zoom, print, and PNG export. Try: filter by department and download a PNG.
5. Hire Requests (/hire-requests) — requisition lifecycle draft → approval → posted. Try: the "Use template" wizard spins up a Library Aide req in seconds.
6. Approvals Inbox (/approvals) — every PAF, hire request, and offer awaiting sign-off. Try: approve, return, or comment on the seeded PAF.
7. Personnel Action Forms (/paf) — promotions, transfers, separations with full audit trail. Try: click New PAF to walk an action through the chain.
8. Recruiting — Postings (/jobs) — public and internal postings backed by approved requisitions. Try: open a posting and use the public Apply link to test the candidate flow.
9. AI Applicant Screening (/screenings) — human-in-the-loop: AI drafts a fit score, recruiters Accept / Edit / Dismiss. Try: select multiple applicants and run a bulk screening pass.
10. Offers (/offers) — generated offer letters with signed candidate response tokens. Try: open a pending offer and preview the candidate-facing page.
11. Preboarding & Onboarding (/preboarding) — task lists, equipment, and provisioning for new hires.
12. Offboarding (/offboarding) — separation checklist with role-aware task templates. Try: start an offboarding from any employee to see the generated tasks.
13. Performance — Review Cycles (/review-cycles) — configure cycles, participants, and calibration sessions.
14. 1-on-1s (/one-on-ones) — templates and meeting notes for manager/employee conversations. Try: open a meeting to see the role-aware question set.
15. 1-on-1 Templates (/one-on-one-templates) — HR admins clone, edit, and publish the manager + employee prompt sets.
16. Cascades (/cascades) — org-wide directives with team responses and an AI rollup summary.
17. Goals & OKRs (/goals) — employee and team goals tied back to review cycles.
18. Cross-Functional Teams (/teams) — self-organizing, cross-departmental teams with charter, members, nested weighted goals, deliverables, meetings, decisions, and an activity feed. Any employee can create a team; visibility is private (members + HR admins).
19. Timekeeping (/timekeeping) — clock in/out, weekly totals, OT and comp-time. Try: edit your exempt weekly schedule or approve a non-exempt timesheet.
20. Public Safety Shift Patterns (/shift-patterns) — multi-week rotations with 207(k) thresholds.
21. Compensation Cycles (/comp-cycles) — run merit and market adjustment cycles with proposals and FLSA checks.
22. HR + Finance — FTE Budget (/hr-finance) — department FTE budgets per fiscal year; powers the requisition budget check.
23. Payroll Export Profiles (/payroll/profiles) — Tyler Munis, BS&A, ADP, Paycom field maps.
24. Policies & Acknowledgements (/policies) — policy library and acknowledgement campaigns.
25. Union Contracts (/cba) — CBAs, terms, effective dates.
26. OSHA 300 / 300A (/osha) — incident log and annual summary.
27. LMS Imports (/lms-imports) — external training completions; maps to TCOLE credits.
28. Training & Transcripts (/training) — course catalog, assignments, and individual transcripts.
29. Compliance — TCOLE / TMRS (/compliance/tcole) — Texas-specific reporting surfaces.
30. Reports & EEO (/reports) — headcount, turnover, comp-ratio, EEO snapshot.
31. Identity & SSO (/admin-identity) — Entra/Okta SAML and SCIM provisioning.
32. Module Settings (/admin-modules) — super-admin toggles to turn entire modules on or off per tenant.
33. Offline PWA Shell (/offline-shell) — installable shell for clock, leave, and approvals; queues actions and syncs in the background when reconnected.
34. ID Badge Templates (/id-badge-templates) — design CR80 badges: fields, colors, default template, public QR verification.
35. Demo Admin (/admin-demo) — provision the demo account and reset its data on demand. Try: click Reset now to revert immediately.

Employee photos & ID badges

• HR uploads to a private storage bucket; signed URLs render the photo throughout the app (profile, org chart, badge PDF).
• Employees cannot replace their own photo — HR-only by RLS and server checks.
• Badge PDFs render at CR80 size (3.375" × 2.125") with a QR code that resolves to /api/public/badge/{serial} for at-a-door verification.
• Revoking a badge flips its public verify page to Revoked immediately.

Org chart

• Built live from employees.manager_id; no separate hierarchy table to maintain.
• Active employees only by default — toggle Include inactive to audit gaps.
• The Unassigned panel lists active employees with no manager and no reports — useful for cleaning up reporting lines.

Reset behavior

• A pg_cron job runs hourly and rolls back any rows the demo user inserted, updated, or deleted in the last 24 hours.
• Reset now on /admin-demo triggers the same rollback immediately.
• Module toggles, security settings, and other super-admin surfaces are out of scope for the demo sandbox revert.

16. HR Manager Onboarding Checklist

Use this checklist the first time you set up employee photos, ID badges, and the org chart. Complete it in order — each step depends on the one before it.

• 1. Open an employee profile

  1. Go to Employees (/employees).
  2. Click any employee row to open /employees/{id}.
  3. Confirm you see the Profile, Photo, and ID Badge tabs.

• 2. Upload a photo

  1. On the employee profile, select the Photo tab.
  2. Click Upload photo and choose a headshot (PNG or JPG under 5 MB).
  3. Crop if needed, then click Save.
  4. Result: The photo appears on the profile card and in the org chart. Employees cannot replace their own photo — only HR can.

• 3. Verify the photo in the org chart

  1. Go to Org Chart (/org-chart).
  2. Find the employee in the tree. Their photo should render on the card.
  3. Try: use the search box or filter by department to narrow the view.

• 4. Review or create a badge template

  1. Go to ID Badge Templates (/id-badge-templates).
  2. Open the Default template, or click New template to design your own.
  3. Pick which fields to show (name, title, department, employee ID, QR code), set primary/accent colors, and upload an org logo.
  4. Click Save template.

• 5. Generate a CR80 badge

  1. Return to the employee profile (/employees/{id}) and select the ID Badge tab.
  2. Pick the template you just reviewed.
  3. Click Generate badge PDF.
  4. Result: A CR80-size PDF (3.375" × 2.125") downloads with the employee photo, fields, and a verification QR code.
  5. Try: print on a CR80 PVC card or laminate sheet.

• 6. Test the QR verification

  1. Scan the QR code on the printed badge with any phone camera.
  2. It resolves to /api/public/badge/{serial}.
  3. Confirm the public page shows the employee name, photo, and Valid status.
  4. Try: click Revoke in the app, then refresh the public page. It should now show Revoked.

• 7. Explore the org chart for reporting gaps

  1. Return to Org Chart (/org-chart).
  2. Click Include inactive if you want to audit the full hierarchy.
  3. Scroll to the Unassigned panel at the bottom — it lists employees with no manager and no direct reports.
  4. Try: use zoom controls, print the chart, or click Export PNG to save a snapshot.

• 8. Batch-photo multiple employees (optional)

  1. Back in Employees (/employees), open each new hire's profile in turn.
  2. Repeat step 2 for each photo.
  3. Refresh the org chart to see the full tree populate with faces.

Tip: If a photo upload fails, check that the file is under 5 MB and that you have the hr_admin or supervisor role. Only HR roles can write to the private employee-photos bucket.

17. Offline-first PWA

CivicPlexus ships as an installable Progressive Web App with an offline-first shell at /offline-shell for the three highest-volume actions: clock in/out, leave requests, and PAF approvals.

Install

1. Open the app in Chrome, Edge, or Safari and tap Install (Address bar → Install app, or Share → Add to Home Screen on iOS).
2. Visit /offline-shell once while online so the service worker caches the shell and stores your employee context.

How it works offline

• Actions queue to IndexedDB in FIFO order with your captured Supabase bearer token.
• When the device reconnects, Background Sync (civicplexus-offline-sync tag) drains the queue against /api/public/hooks/offline-replay — even if every tab is closed.
• Safari (no SyncManager) falls back to a drain-queue postMessage when any tab is open.
• The sticky Offline banner shows online/offline state, queued action count, and a Sync now button.

Modules covered

Everything else falls back to a network-first cached navigation; static assets are CacheFirst.

17. Elected Officials & Board Appointees

Governance is a first-class module for tracking elected officials, board members, and commission appointees separately from employees.

17.1 Concepts

• Body — a governing body (Council, Board, Commission). Sets pay rules: per_meeting_amount, chair_bonus_amount, per_diem_amount, and pay_absent.
• Seat — a numbered position on a body (e.g., Place 3, District 2, At-Large).
• Official — the person. Public visibility is controlled per record; contact details are private by default.
• Term — the assignment of an official to a seat with start/end dates, oath, and status (active, resigned, removed, expired).
• Disclosure — Chapter 176 conflict-of-interest, financial statements, ethics acknowledgments.

17.2 Lifecycle

1. Create body & seats — HR admin or City Clerk (admin-officials).
2. Add official record — name, photo, bio, contact. Set public_visible and public_show_contact flags.
3. Create term — link official + seat, set appointment date and term end.
4. Swear in — records oath date/administrator, flips term to active.
5. Attendance & pay — log meetings, mark attendance, click Generate pay to create draft reimbursements (idempotent per meeting/kind).
6. Disclosures — track required filings and due dates.
7. End term — resignation, removal, or expiration. Triggers immediate notification to HR admins and City Clerk.
8. Public roster — /officials shows only records with public_visible = true; contact is masked unless public_show_contact = true.

17.3 New roles

• City Clerk (city_clerk) — full CRUD on bodies, seats, officials, terms, meetings, attendance, disclosures. Runs pay generation and roster exports.
• Elected Official (elected_official) — read own record and term, submit their own disclosures. No access to other employee data.
• HR admins retain full override.

17.4 Notifications

A daily pg_cron sweep (notify_officials_expiring) alerts HR admins and City Clerks when a term is within 120 days of expiration (de-duplicated every 30 days). Resignations and removals fire immediately.

17.5 Exports

From /officials (public) and /admin-officials (clerk):

• CSV — spreadsheet export of the visible roster.
• CSV (full history) (clerk only) — includes ended terms and disclosure history.
• PDF — opens a print-ready view; use browser "Save as PDF".

The public CSV/PDF respects public_visible and public_show_contact. Clerk exports include seat, term dates, oath, and disclosure status.