db/herodb_old/src/models/gov/README.md

Corporate Governance Module

This directory contains the core data structures used for corporate governance functionality. These models serve as the foundation for managing companies, shareholders, meetings, voting, resolutions, committees, and more in any organizational context.

Overview

The governance models implement the Serde traits (Serialize/Deserialize) and database traits (Storable, SledModel), which allows them to be stored and retrieved using the generic SledDB implementation. Each model provides:

• A struct definition with appropriate fields
• Serde serialization through derive macros
• Methods for database integration through the SledModel trait
• Utility methods for common operations

Core Models

Company (company.rs)

The Company model represents a company entity with its basic information:

• Company: Main struct with fields for company information
  • Basic details: name, registration number, incorporation date
  • Contact information: email, phone, website, address
  • Business information: business type, industry, description
  • Status tracking: current status, timestamps
• CompanyStatus: Enum for possible company statuses (Active, Inactive, Suspended)
• BusinessType: String-based type with validation for business types (Corporation, Partnership, LLC, etc.)

Key methods:

• add_shareholder(): Add a shareholder to the company
• link_to_circle(): Link the company to a Circle for access control
• link_to_customer(): Link the company to a Customer in the biz module
• get_resolutions(): Get all resolutions for this company

Shareholder (shareholder.rs)

The Shareholder model represents a shareholder of a company:

• Shareholder: Main struct with fields for shareholder information
  • Identifiers: id, company_id, user_id
  • Ownership details: shares, percentage
  • Type and timestamps: shareholder type, since date, created/updated timestamps
• ShareholderType: Enum for possible shareholder types (Individual, Corporate)

Key methods:

• update_shares(): Update the shares owned by this shareholder

Meeting (meeting.rs)

The Meeting model represents a board meeting of a company:

• Meeting: Main struct with fields for meeting information
  • Basic details: id, company_id, title, date, location, description
  • Status and content: meeting status, minutes
  • Timestamps and attendees: created/updated timestamps, list of attendees
• Attendee: Represents an attendee of a meeting
  • Details: id, meeting_id, user_id, name, role, status, created timestamp
• MeetingStatus: Enum for possible meeting statuses (Scheduled, Completed, Cancelled)
• AttendeeRole: Enum for possible attendee roles (Coordinator, Member, Secretary, etc.)
• AttendeeStatus: Enum for possible attendee statuses (Confirmed, Pending, Declined)

Key methods:

• add_attendee(): Add an attendee to the meeting
• update_status(): Update the status of the meeting
• update_minutes(): Update the meeting minutes
• find_attendee_by_user_id(): Find an attendee by user ID
• confirmed_attendees(): Get all confirmed attendees
• link_to_event(): Link the meeting to a Calendar Event
• get_resolutions(): Get all resolutions discussed in this meeting

User (user.rs)

The User model represents a user in the governance system:

• User: Main struct with fields for user information
  • Basic details: id, name, email, password
  • Role information: company, role
  • Timestamps: created/updated timestamps

Vote (vote.rs)

The Vote model represents a voting item for corporate decision-making:

• Vote: Main struct with fields for vote information
  • Basic details: id, company_id, title, description
  • Timing: start_date, end_date
  • Status and timestamps: vote status, created/updated timestamps
  • Options and results: list of vote options, list of ballots, private group
• VoteOption: Represents an option in a vote
  • Details: id, vote_id, text, count, min_valid
• Ballot: Represents a ballot cast by a user
  • Details: id, vote_id, user_id, vote_option_id, shares_count, created timestamp
• VoteStatus: Enum for possible vote statuses (Open, Closed, Cancelled)

Key methods:

• add_option(): Add a voting option to this vote
• add_ballot(): Add a ballot to this vote
• get_resolution(): Get the resolution associated with this vote

Resolution (resolution.rs)

The Resolution model represents a board resolution:

• Resolution: Main struct with fields for resolution information
  • Identifiers: id, company_id, meeting_id, vote_id
  • Content: title, description, text
  • Status and tracking: resolution status, proposed_by, proposed_at, approved_at, rejected_at
  • Timestamps and approvals: created/updated timestamps, list of approvals
• Approval: Represents an approval of a resolution by a board member
  • Details: id, resolution_id, user_id, name, approved, comments, created timestamp
• ResolutionStatus: Enum for possible resolution statuses (Draft, Proposed, Approved, Rejected, Withdrawn)

Key methods:

• propose(): Propose the resolution
• approve(): Approve the resolution
• reject(): Reject the resolution
• withdraw(): Withdraw the resolution
• add_approval(): Add an approval to the resolution
• find_approval_by_user_id(): Find an approval by user ID
• get_approvals(): Get all approvals
• approval_count(): Get approval count
• rejection_count(): Get rejection count
• link_to_meeting(): Link this resolution to a meeting
• link_to_vote(): Link this resolution to a vote
• get_meeting(): Get the meeting associated with this resolution
• get_vote(): Get the vote associated with this resolution

Committee (committee.rs)

The Committee model represents a board committee:

• Committee: Main struct with fields for committee information
  • Basic details: id, company_id, name, description, purpose
  • Integration: circle_id
  • Timestamps and members: created/updated timestamps, list of members
• CommitteeMember: Represents a member of a committee
  • Details: id, committee_id, user_id, name, role, since, created timestamp
• CommitteeRole: Enum for possible committee roles (Chair, ViceChair, Secretary, Member, Advisor, Observer)

Key methods:

• add_member(): Add a member to the committee
• find_member_by_user_id(): Find a member by user ID
• remove_member(): Remove a member from the committee
• link_to_circle(): Link this committee to a Circle for access control
• get_member_users(): Get all users who are members of this committee

Model Relationships

The following diagram illustrates the relationships between the governance models:

graph TD
    Company --> |has many| Shareholder
    Company --> |has many| Meeting
    Company --> |has many| Resolution
    Company --> |has many| Vote
    Company --> |has many| Committee
    
    Meeting --> |has many| Attendee
    Attendee --> |is a| User
    
    Resolution --> |can be linked to| Meeting
    Resolution --> |can be linked to| Vote
    Resolution --> |has many| Approval
    
    Vote --> |has many| VoteOption
    Vote --> |has many| Ballot
    Ballot --> |cast by| User
    
    Committee --> |has many| CommitteeMember
    CommitteeMember --> |is a| User

Key Relationships

• Company-Shareholder: A company has multiple shareholders who own shares in the company
• Company-Meeting: A company holds multiple meetings for governance purposes
• Company-Resolution: A company creates resolutions that need to be approved
• Company-Vote: A company conducts votes on various matters
• Company-Committee: A company can have multiple committees for specialized governance functions
• Meeting-Resolution: Resolutions can be discussed and approved in meetings
• Resolution-Vote: Resolutions can be subject to formal voting
• User-Governance: Users participate in governance as shareholders, meeting attendees, committee members, and by casting votes

Integration with Other Modules

The governance module integrates with other modules in the system:

Integration with Biz Module

• Company-Customer: Companies can be linked to customers in the biz module
• Company-Contract: Companies can be linked to contracts in the biz module
• Shareholder-Customer: Shareholders can be linked to customers in the biz module
• Meeting-Invoice: Meetings can be linked to invoices for expense tracking

Integration with MCC Module

• Meeting-Calendar/Event: Meetings can be linked to calendar events in the mcc module
• User-Contact: Users can be linked to contacts in the mcc module
• Vote-Message: Votes can be linked to messages for notifications

Integration with Circle Module

• Company-Circle: Companies can be linked to circles for group-based access control
• User-Member: Users can be linked to members for role-based permissions

Detailed Data Model

A more detailed class diagram showing the fields and methods of each model:

classDiagram
    class Company {
        +u32 id
        +String name
        +String registration_number
        +DateTime incorporation_date
        +String fiscal_year_end
        +String email
        +String phone
        +String website
        +String address
        +BusinessType business_type
        +String industry
        +String description
        +CompanyStatus status
        +DateTime created_at
        +DateTime updated_at
        +add_shareholder()
        +link_to_circle()
        +link_to_customer()
        +get_resolutions()
    }
    
    class Shareholder {
        +u32 id
        +u32 company_id
        +u32 user_id
        +String name
        +f64 shares
        +f64 percentage
        +ShareholderType type_
        +DateTime since
        +DateTime created_at
        +DateTime updated_at
        +update_shares()
    }
    
    class Meeting {
        +u32 id
        +u32 company_id
        +String title
        +DateTime date
        +String location
        +String description
        +MeetingStatus status
        +String minutes
        +DateTime created_at
        +DateTime updated_at
        +Vec~Attendee~ attendees
        +add_attendee()
        +update_status()
        +update_minutes()
        +find_attendee_by_user_id()
        +confirmed_attendees()
        +link_to_event()
        +get_resolutions()
    }
    
    class User {
        +u32 id
        +String name
        +String email
        +String password
        +String company
        +String role
        +DateTime created_at
        +DateTime updated_at
    }
    
    class Vote {
        +u32 id
        +u32 company_id
        +String title
        +String description
        +DateTime start_date
        +DateTime end_date
        +VoteStatus status
        +DateTime created_at
        +DateTime updated_at
        +Vec~VoteOption~ options
        +Vec~Ballot~ ballots
        +Vec~u32~ private_group
        +add_option()
        +add_ballot()
        +get_resolution()
    }
    
    class Resolution {
        +u32 id
        +u32 company_id
        +Option~u32~ meeting_id
        +Option~u32~ vote_id
        +String title
        +String description
        +String text
        +ResolutionStatus status
        +u32 proposed_by
        +DateTime proposed_at
        +Option~DateTime~ approved_at
        +Option~DateTime~ rejected_at
        +DateTime created_at
        +DateTime updated_at
        +Vec~Approval~ approvals
        +propose()
        +approve()
        +reject()
        +add_approval()
        +link_to_meeting()
        +link_to_vote()
    }
    
    class Committee {
        +u32 id
        +u32 company_id
        +String name
        +String description
        +String purpose
        +Option~u32~ circle_id
        +DateTime created_at
        +DateTime updated_at
        +Vec~CommitteeMember~ members
        +add_member()
        +find_member_by_user_id()
        +remove_member()
        +link_to_circle()
        +get_member_users()
    }
    
    Company "1" -- "many" Shareholder: has
    Company "1" -- "many" Meeting: holds
    Company "1" -- "many" Vote: conducts
    Company "1" -- "many" Resolution: issues
    Company "1" -- "many" Committee: establishes
    Meeting "1" -- "many" Attendee: has
    Meeting "1" -- "many" Resolution: discusses
    Vote "1" -- "many" VoteOption: has
    Vote "1" -- "many" Ballot: collects
    Vote "1" -- "1" Resolution: decides
    Resolution "1" -- "many" Approval: receives
    Committee "1" -- "many" CommitteeMember: has

Usage

These models are used by the governance module to manage corporate governance. They are typically accessed through the database handlers that implement the generic SledDB interface.