Member Model Documentation

Overview

The Member model provides a unified representation for both human team members and AI agents participating in projects. This abstraction allows CODITECT to treat humans and AI agents uniformly in task assignment, capacity planning, and collaboration workflows while maintaining type-specific attributes through flexible metadata.

Model Structure

Core Fields

Field	Type	Description	Constraints
member_id	UUID	Unique member identifier	Primary key, auto-generated
tenant_id	UUID	Associated tenant	Foreign key to Tenant
user_id	UUID (Optional)	Link to User if human	Foreign key to User
member_type	MemberType (Enum)	Human or Agent	Required
name	String	Display name	Required
email	String (Optional)	Email address	Required for humans
avatar_url	String (Optional)	Profile image URL	Valid URL format
status	MemberStatus (Enum)	Current employment status	Required
capabilities	Vec	Skills or agent capabilities	Flexible tags
availability	Availability (Enum)	Current availability	Required
capacity	Capacity	Work capacity tracking	Required
metadata	JSON (Optional)	Type-specific data	Flexible structure
created_at	DateTime	Creation timestamp	Auto-set
updated_at	DateTime	Last modification	Auto-updated

Enumerations

MemberType Enum

enum MemberType {
    Human,   // Human team member
    Agent    // AI agent
}

MemberStatus Enum

enum MemberStatus {
    Active,      // Currently active
    Inactive,    // Temporarily inactive
    Pending,     // Awaiting activation
    OnLeave,     // On leave (humans)
    Terminated   // No longer with organization
}

Availability Enum

enum Availability {
    Available,      // Ready for new tasks
    Busy,           // Working at capacity
    DoNotDisturb,   // Focus time
    Offline         // Not available
}

Capacity Structure

Field	Type	Description	Usage
max_concurrent_tasks	i32	Maximum parallel tasks	Both types
current_task_count	i32	Active task count	Both types
weekly_hours	f32 (Optional)	Work hours per week	Humans only
tokens_per_hour	i32 (Optional)	Processing capacity	Agents only

Type-Specific Patterns

Human Members

{
  "member_id": "123e4567-e89b-12d3-a456-426614174000",
  "tenant_id": "456e7890-e89b-12d3-a456-426614174000",
  "user_id": "789e0123-e89b-12d3-a456-426614174000",
  "member_type": "Human",
  "name": "Jane Smith",
  "email": "jane.smith@example.com",
  "avatar_url": "https://avatars.example.com/jane-smith.jpg",
  "status": "Active",
  "capabilities": ["rust", "python", "architecture", "code-review"],
  "availability": "Available",
  "capacity": {
    "max_concurrent_tasks": 5,
    "current_task_count": 2,
    "weekly_hours": 40.0,
    "tokens_per_hour": null
  },
  "metadata": {
    "department": "Engineering",
    "location": "San Francisco",
    "timezone": "America/Los_Angeles",
    "start_date": "2024-01-15",
    "manager_id": "manager-uuid"
  }
}

Agent Members

{
  "member_id": "987e6543-e89b-12d3-a456-426614174000",
  "tenant_id": "456e7890-e89b-12d3-a456-426614174000",
  "user_id": null,
  "member_type": "Agent",
  "name": "Code Review Agent",
  "email": null,
  "avatar_url": "https://avatars.example.com/ai-reviewer.svg",
  "status": "Active",
  "capabilities": ["code_review", "security_analysis", "performance_optimization"],
  "availability": "Available",
  "capacity": {
    "max_concurrent_tasks": 10,
    "current_task_count": 3,
    "weekly_hours": null,
    "tokens_per_hour": 50000
  },
  "metadata": {
    "agent_type": "reviewer",
    "provider": "claude",
    "model": "claude-3-opus",
    "agent_config_id": "config-uuid",
    "instance_id": "instance-uuid"
  }
}

Database Schema

Primary Storage Pattern

Key: /{tenant_id}/members/{member_id}
Value: JSON serialized Member object

Secondary Indexes

# Members by type
/{tenant_id}/members_by_type/{member_type} -> [member_ids]

# Members by status
/{tenant_id}/members_by_status/{status} -> [member_ids]

# Available members
/{tenant_id}/available_members -> [member_ids]

# Members by capability
/{tenant_id}/members_by_capability/{capability} -> [member_ids]

# Human members by user
/{tenant_id}/members_by_user/{user_id} -> member_id

Key Methods

Factory Methods

impl Member {
    // Create human member
    fn new_human(
        tenant_id: Uuid,
        user_id: Uuid,
        name: String,
        email: String,
        capabilities: Vec<String>
    ) -> Self
    
    // Create agent member
    fn new_agent(
        tenant_id: Uuid,
        name: String,
        capabilities: Vec<String>,
        tokens_per_hour: i32
    ) -> Self
}

Availability Management

impl Member {
    fn is_available(&self) -> bool
    fn can_take_task(&self) -> bool
    fn update_availability(&mut self, availability: Availability)
}

Capacity Management

impl Member {
    fn assign_task(&mut self) -> Result<(), String>
    fn complete_task(&mut self)
    fn get_utilization(&self) -> f32
}

Capability Management

impl Member {
    fn has_capability(&self, capability: &str) -> bool
    fn add_capability(&mut self, capability: String)
    fn remove_capability(&mut self, capability: &str)
    fn matches_requirements(&self, required: &[String]) -> bool
}

Business Rules

Assignment Rules

1. Availability Check: Must be Active status and Available
2. Capacity Check: current_task_count < max_concurrent_tasks
3. Capability Match: Member must have required capabilities
4. Type Compatibility: Some tasks may require human/agent specifically

Status Transitions

Pending -> Active -> Inactive -> Active
                  -> OnLeave -> Active
                  -> Terminated

Any Status -> Terminated (with proper authorization)

Capacity Defaults

• Human: 5 concurrent tasks, 40 hours/week
• Agent: 10 concurrent tasks, provider-specific token limits

API Endpoints

Member Management

• POST /api/members - Create new member
• GET /api/members/{member_id} - Get member details
• PUT /api/members/{member_id} - Update member
• DELETE /api/members/{member_id} - Archive member
• GET /api/members?type={type}&status={status}&capability={cap} - List members

Availability Operations

• PUT /api/members/{member_id}/availability - Update availability
• GET /api/members/available?capabilities={caps} - Find available members
• GET /api/members/{member_id}/utilization - Get utilization metrics

Capacity Management

• GET /api/members/{member_id}/tasks - List assigned tasks
• GET /api/members/{member_id}/workload - Get workload analysis

Related Code

Source Files

• Model: /src/models/member.rs
• Repository: /src/db/repositories/member_repository.rs
• API Handler: /src/api/handlers/member_handlers.rs
• Tests: /src/models/tests/member_tests.rs

Integration Points

• User Model: Linked for human members
• Agent Models: Agent members reference AgentConfig
• Task Model: Tasks assigned to members
• Project Model: Members work on projects

Use Cases

Team Formation

// Find available members with required skills
let required_skills = vec!["rust", "security"];
let available_members = member_repo
    .find_available_with_capabilities(&tenant_id, &required_skills)
    .await?;

Task Assignment

// Assign task to least loaded member
let member = member_repo
    .find_least_loaded_with_capability(&tenant_id, "python")
    .await?;
    
if member.can_take_task() {
    member.assign_task()?;
    // Assign actual task in task system
}

Capacity Planning

// Calculate team capacity
let team_members = member_repo
    .list_by_project(&tenant_id, &project_id)
    .await?;
    
let total_capacity: i32 = team_members
    .iter()
    .filter(|m| m.is_available())
    .map(|m| m.capacity.max_concurrent_tasks - m.capacity.current_task_count)
    .sum();

Human-Agent Collaboration

Mixed Teams

Members support mixed human-agent teams where:

• Humans provide creativity and judgment
• Agents handle repetitive tasks
• Both collaborate through the same interfaces

Handoff Patterns

// Agent completes initial work
agent_member.complete_task();

// Human reviews and refines
human_member.assign_task()?;

Capability Complementarity

• Agents: High-volume, consistent quality
• Humans: Complex decisions, creative solutions
• System assigns based on task requirements

Performance Considerations

Indexing Strategy

• Primary index on member_id for direct lookups
• Secondary indexes for filtering and search
• Capability index for skill-based queries
• Availability index for assignment algorithms

Caching

• Cache frequently accessed members
• Cache capability searches
• Invalidate on status/availability changes

Security & Privacy

Access Control

• View own member profile
• Managers view team members
• Admin view all members
• Limited fields for cross-team viewing

Data Privacy

• PII (email, metadata) encrypted at rest
• Audit trail for all modifications
• GDPR compliance for human members
• Agent credentials stored securely

Monitoring & Analytics

Metrics

• Member utilization rates
• Task completion times by member
• Capability coverage analysis
• Availability patterns
• Human vs agent performance

Reports

• Team capacity dashboard
• Skills matrix
• Utilization trends
• Burndown analysis
• Cost per member type

Future Enhancements

Advanced Features

1. Skill Proficiency Levels: Beyond binary capabilities
2. Learning Tracking: Capability growth over time
3. Preference Matching: Task preference scoring
4. Team Recommendations: AI-powered team formation

Integration Expansions

1. Calendar Integration: Sync human availability
2. Performance Reviews: Link to member profiles
3. Training Systems: Capability development
4. External Contractors: Third member type

Automation

1. Auto-scaling: Spawn agent members based on load
2. Skill Detection: Auto-detect capabilities from work
3. Optimal Assignment: ML-based task routing
4. Predictive Availability: Forecast member availability

---

Last Updated: 2025-08-29 Version: 1.0