Skip to content

HOA — Homeowners' Association

The HOA module supports the elected committee that oversees facility governance: members, meetings, motions, and (where enabled) read or write access to facility finances.

What residents see

Residents have an HOA tab:

  • Committee members — who's elected, their role (Chair, Treasurer, Secretary, etc.), and their term dates.
  • Public finances — if your facility has Public Finances enabled, residents see a high-level summary of facility income/expenses for the current period (no per-unit detail, no PII).
  • Upcoming AGM / meetings — scheduled dates, agenda, location.
  • Past minutes — meeting minutes from prior gatherings.
  • Motions — current motions open for comment or vote.
  • Run for committee — resident can apply to stand for an open position.

What committee members see

Elected committee members have an enhanced view:

  • Committee dashboard — pending motions, upcoming meetings, finance summary (if write access granted).
  • Draft minutes — committee secretary drafts here, others review before publishing to residents.
  • Motion management — propose, sponsor, table, withdraw motions.
  • Committee-only chat — the committee is automatically a chat group in the Messaging module for closed discussions.

What facility admins do

The HOA owns its own access. As of the November 2025 self-governance update, the elected board / secretary controls whether facility admins can see the HOA module at all. See Self-governing access below for the full rules; the workflows in this section describe the surface facility admins use when the HOA has granted them access.

Manage committee membership

Bootstrap-only. Once the HOA has at least one active board member, adding or removing members shifts to the elected secretary. Mgmt only retains add-board powers while the active board count is zero (so a brand-new estate can seed its first member). The CautaReside operator can always seed regardless.

Settings → HOA → Committee Roster: - Add or remove members. - Set their role (President, Vice-President, Treasurer, Secretary, Member-at-Large). - Term start + end dates. - Each member's HOA portal access is tied to these dates — terms ending automatically revoke access.

The roster is the source of truth for who has elevated HOA access:

  • Position Secretary → full HOA edit + can add other board members.
  • Any other active position (President, Vice-President, Treasurer, Member-at-Large) → board (read everything + vote / motion / minutes write).
  • No active roster row → resident (public content only).

The HOA dropdown in Settings → Users → Module Roles is read-only for facility users because of this binding. Change someone's role by editing the Board roster, not the user record.

Configure access to finances

Two layers of access:

  1. Read access — committee sees the high-level finance summary (income, expenses by category, current bank balance) but can't change anything.
  2. Read + Write access — committee can mark expenses approved / denied, generate reports, run end-of-year reconciliation.

Most facilities run with Read-only for the committee and keep financial controls with management. Operators with elected treasurers who actively run the books grant Read + Write.

Configure in Settings → Billing Module Config → HOA finance billing access.

Manage public finances

Settings → HOA → Public Finances: - Toggle on to publish a finance summary to all residents. - Choose what to show: income only, income + expense categories, income + expenses + balance. - Refresh frequency (real-time, monthly, end-of-year only).

When on, residents see this on their HOA tab. When off, only the committee + management see finance details.

Schedule a meeting

HOA → Meetings → New Meeting: - Type (AGM, Quarterly, Emergency, Sub-committee) - Date + time + location (or virtual link) - Agenda items (committee can add to this) - Required notice period (typical 7-14 days for AGMs)

When scheduled, the system: - Sends a broadcast to all residents (if AGM) or committee (if closed) - Tracks RSVPs - Captures attendance during the meeting (committee secretary marks attendees)

Manage motions

A motion has lifecycle: - Draft — committee member is composing - Open for comment — residents can comment, no vote yet - Open for vote — residents vote yes/no/abstain - Closed — voting period over, result published - Implemented / Rejected — final disposition

Motion types: - Procedural (e.g. "elect Treasurer") - Financial (e.g. "approve special assessment of GHS 500/unit") - Operational (e.g. "extend pool hours to 10 PM")

Reports

  • Member turnout at meetings
  • Motion success rate
  • Committee tenure (who's served, for how long)
  • Communication audit (broadcasts sent, ack rates)

Self-governing access

The HOA module operates as a self-governing surface. Three rules shape who sees what:

1. Roster drives roles

Adding a user to HOA → Board with an active term grants them the matching elevated module role automatically. Removing them or letting their term end reverts them to resident. There is no separate permission knob to keep in sync.

2. Adding board members shifts to the HOA

Once a facility has at least one active board row, only the secretary (or the CautaReside operator) can add further members. Mgmt is locked out of POST /api/hoa/board to prevent self-promotion. Bootstrap exception: while the active board count is zero, mgmt may seed the first member so a brand-new estate isn't stuck.

3. Mgmt visibility is HOA-controlled

Facility admins (the hoa: mgmt module role) only see the HOA module when the board / secretary grants access. Settings → HOA → Mgmt Access carries two toggles:

  • Allow mgmt to view HOA — when off, facility admins see no HOA tab, no documents, no meetings, no finances. Required for any of the workflows in What facility admins do above to be reachable.
  • Allow mgmt to edit HOA — only meaningful when the view toggle is on.

The CautaReside platform operator has full access and is unaffected by these toggles — needed for support and compliance.

New user default

Every new user is created with hoa: resident so they can see public HOA documents, public finances, and the motions feed by default. Pick a higher tier (board / secretary / mgmt) on the Add User form to grant elevated HOA access. The mgmt tier additionally needs the per-facility view-toggle on for the user to actually see anything.

Documents

Visibility model change (May 2026). Residents now have read-only access to every Published HOA document. The previous three-tier model (Public / Committee / Board-only) was replaced per operator directive — "residents are to have read-only access to all docs." Drafts and Archived rows remain hidden from residents regardless of tier.

Documents are uploaded by the secretary (or the CautaReside operator):

  • Single upload — pick file (≤ 10 MB), add a title, optionally tag a committee, choose Draft or Publish.
  • Bulk upload — drop multiple files at once; each lands as a Draft for review before publication.
  • Replace file — same row, new version. The previous version is kept in history (auto-version cap of 5 — the oldest version is deleted to make room when a 6th replacement uploads).
  • Delete — secretary can delete docs they've published; the row is soft-deleted with the deleting user and timestamp on the audit trail.

What residents see: - Every Published HOA document, read-only. - Version history is collapsed — they see the current Published version only. - Cannot upload, edit, or delete.

What the board sees: - Everything residents see, plus Draft + Archived rows. - The board can comment on Drafts before the secretary publishes.

What mgmt sees: - Only when the HOA has granted Allow mgmt to view HOA (see Self-governing access). When granted, mgmt sees the same view as the board.

Public Finances detail

When enabled, the public finances view shows residents: - This month's income (rent, service, parking, fines, other) - This month's expenses by category (utilities, salaries, repairs, contracts, capital, other) - Current balance (operating + reserve fund) - Year-to-date comparison

It does NOT show: - Per-unit balances or arrears - Specific resident payments - Salary detail (only total salaries, not who earns what) - Bank account numbers - Vendor invoices in detail

Privacy is preserved while still giving residents the budget transparency that healthy estates rely on.

Tips

  • Term limits keep governance fresh — set 2-3 year terms with staggered renewal so the committee doesn't fully refresh every cycle.
  • Public finances build trust — residents who don't know how their service charge is spent assume the worst. Showing category-level numbers (without PII) silences a lot of complaints.
  • Schedule AGMs early — even with the digital tooling, Ghanaian estates often struggle with quorum. 30-day notice + Telegram reminder + in-person date pinned on the gate gets you there.
  • Train new committee members on the HOA module before their first meeting — this saves you from re-explaining the same workflows to every new chair.

Process flows

End-to-end procedures the board / secretary / mgmt team runs day-to- day. Steps are anchored to the actual UI labels.

Schedule a meeting (board / committee / AGM)

  1. HOA → Meetings → + New Meeting.
  2. Type (AGM / Quarterly / Emergency / Sub-committee), date + time + location (or virtual link), required notice period (typical 7-14 days for standard, 30+ for AGM).
  3. Tick the agenda items the meeting will cover (or add new ones inline). Committee members can add to the agenda right up to 24 h before.
  4. Schedule — broadcast goes out to the relevant audience (residents for AGM; committee + secretary for closed). RSVP tracking opens.
  5. Day of: secretary marks attendance during the meeting; the system computes quorum live and surfaces a banner if you're short.

Draft and publish meeting minutes

  1. HOA → Meetings → pick the meeting → Draft minutes.
  2. The system pre-fills attendance + agenda items + any motions taken. Secretary edits + adds free-text decisions / discussion notes.
  3. Save as Draft — visible to the board for review only. Add reviewers via the share row; reviewers see a notification.
  4. After board sign-off, Publish — minutes become Public-tier visible to all residents (or Committee-tier if the meeting was closed).
  5. Once published, edits create a tracked-change revision; the original is preserved for the audit trail.

Propose + run a motion (vote)

  1. HOA → Motions → + New Motion.
  2. Pick motion type (Procedural / Financial / Operational), enter the resolution text, set comment + voting windows.
  3. Open for comment — residents can comment + ask questions for the configured window (typically 7 days).
  4. Based on comments, sponsor can edit the motion text or Withdraw before voting opens.
  5. Open for vote — eligible voters get push + email; ballots open for the configured window. Live tally visible to the board only.
  6. Close — motion result published to all residents on the motions feed. Implemented or rejected.

Add a board member

Secretary path — mgmt is locked out once the board has at least one active member; see Self-governing access above.

  1. HOA → Board → + Add member.
  2. Pick the user from the dropdown (must be an active resident on the facility).
  3. Set position (President / Vice-President / Treasurer / Secretary / Member-at-Large) and term start + end dates.
  4. Save — module role auto-syncs (Secretary → secretary, anyone else → board). User receives a welcome email with the new permissions.
  5. The roster row drives the user's HOA tier from now on; removing the row or letting the term expire reverts them to resident.

Manage HOA documents

  1. HOA → Documents → + Upload (or + Bulk upload for multiple files at once).
  2. Pick the file (≤ 10 MB each). Add a title. Optionally tag a committee.
  3. Save as Draft to review with the board before publication, or Publish directly.
  4. After publication, every resident sees the document in their read-only HOA → Documents view. The board can comment on Drafts.
  5. Replacing a file — open the doc → Replace file → upload the new version. The previous version is kept in history (auto-versioning cap is 5 — the oldest is deleted when a 6th replacement is uploaded).
  6. Deleting a doc — secretary opens the doc → Delete. Soft- deletes the row with deleting user + timestamp on the audit trail; cannot be undone from the UI but the CautaReside operator can restore via the audit log.

HOA dashboard

HOA → Dashboard is a separate tab with KPI tiles + charts for the board: meeting attendance trend, motion outcomes (success / withdrawn / rejected), committee tenure, recent broadcasts. Driven by the same period selector pattern as other module dashboards.

Balance sheet (when finance access is granted)

If the HOA has been granted finance read access (see Configure access to finances above), the board sees a Balance Sheet tab inside Billing — the same view as facility mgmt. Operator-friendly default layout (assets / liabilities / equity), with the full GAAP structure available when Settings → Billing → Balance sheet enabled is on.