Supervisor Role

The Supervisor role serves as middle management in the organizational hierarchy. Supervisors oversee Credit Officers, approve loan applications, and monitor team performance.

Core Responsibilities

Supervisors are responsible for:

Team Management: Overseeing assigned Credit Officers
Loan Approval: Reviewing and approving/rejecting loan applications
Performance Monitoring: Tracking officer performance and portfolio health
Territory Oversight: Managing operations across supervised unions
Reporting: Generating reports on team activities and metrics

Supervisor-Officer Hierarchy

Data Model Relationship

The supervisor-officer relationship is established through the supervisorId field:

model User {
  id             String  @id @default(cuid())
  email          String  @unique
  role           Role
  
  // Credit Officer links to their Supervisor
  supervisorId   String?
  supervisor     User?   @relation("SupervisorToOfficers", fields: [supervisorId], references: [id])
  
  // Supervisor has many Credit Officers
  creditOfficers User[]  @relation("SupervisorToOfficers")
  
  // ...
}

Relationship Setup

When creating a Credit Officer, admins or supervisors must set the supervisorId:

// POST /api/users
{
  "email": "officer@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "role": "CREDIT_OFFICER",
  "supervisorId": "clx...",  // Links to supervisor
  "password": "securePassword123"
}

A Supervisor can have multiple Credit Officers, but each Credit Officer reports to only one Supervisor.

User Management

Creating Credit Officers

Supervisors can create Credit Officer accounts:

// POST /api/users
// user.routes.ts:58-63
// Requires: requireAdminOrBranchManager middleware

When a supervisor creates a user:

The new user’s role must be CREDIT_OFFICER
The supervisorId is automatically set to the creating supervisor
The new officer inherits territorial assignments

Viewing Team Members

Supervisors can view all Credit Officers under their supervision:

// GET /api/supervisor-reports/officers
// supervisor-reports.routes.ts:55-58
// Returns list of Credit Officers where supervisorId matches current user

Supervisors cannot create other supervisors or admin accounts. They can only create Credit Officers.

Loan Approval Authority

Approval Workflow

Supervisors are the gatekeepers for loan disbursement:

Approving Loans

Supervisors can approve loans using the status update endpoint:

// PUT /api/loans/:id/status
// loan.routes.ts:65-71
// Requires: requireBranchManager (includes ADMIN and SUPERVISOR)
{
  "status": "APPROVED",
  "notes": "Reviewed and approved. Member has good repayment history."
}

Rejecting Loans

Supervisors can reject applications with reasons:

// PUT /api/loans/:id/status
{
  "status": "REJECTED",
  "notes": "Insufficient documentation. Request member to provide updated employment letter."
}

When rejecting loans, always provide clear notes explaining the reason. This helps Credit Officers understand what’s needed.

Loan Disbursement

After approval, supervisors can disburse loans:

// POST /api/loans/:id/disburse
// loan.routes.ts:73-79
// Requires: requireBranchManager middleware
{
  "disbursementDate": "2024-03-15T10:00:00Z",
  "disbursementMethod": "TRANSFER",
  "reference": "TXN123456",
  "notes": "Transferred to member's bank account"
}

Loan Assignment

Supervisors can assign or reassign loans to officers:

// POST /api/loans/:id/assign
// loan.routes.ts:81-87
{
  "assignedOfficerId": "clx...",
  "reason": "Reassigning to officer with capacity in this area"
}

Union Management

Creating Unions

Supervisors can create new unions:

// POST /api/unions
// union.routes.ts:14-19
// Requires: requireRole(Role.ADMIN, Role.SUPERVISOR)
{
  "name": "Downtown Potters Union",
  "location": "Central District",
  "address": "123 Main Street",
  "creditOfficerId": "clx..."  // Must be a supervised officer
}

Viewing Supervised Unions

Supervisors see all unions managed by their Credit Officers:

// GET /api/unions
// Returns unions where:
// - Union.creditOfficerId IN (supervised officer IDs)
// - OR user is ADMIN/SUPERVISOR (see all)

Supervisors cannot update or delete unions. Only admins have that authority. This prevents accidental territorial changes.

Reporting & Analytics

Supervisor Dashboard

Supervisors have access to a dedicated reporting dashboard:

// GET /api/supervisor-reports/dashboard
// supervisor-reports.routes.ts:24-28
// Requires: requireRoles(["SUPERVISOR", "ADMIN"])

The dashboard includes:

Total Credit Officers supervised
Total unions in territory
Total members across all supervised unions
Loan portfolio summary (active, completed, defaulted)
Disbursement and repayment totals
Collection rate percentage

Report Generation

Supervisors can generate detailed performance reports:

// POST /api/supervisor-reports/generate
// supervisor-reports.routes.ts:31-34
{
  "reportType": "MONTHLY",
  "periodStart": "2024-03-01T00:00:00Z",
  "periodEnd": "2024-03-31T23:59:59Z",
  "title": "March 2024 Territory Report"
}

Report data is stored in the ReportSession model:

model ReportSession {
  id           String @id @default(cuid())
  supervisorId String
  supervisor   User   @relation("SupervisorReports", fields: [supervisorId], references: [id])
  
  reportType  ReportType @default(CUSTOM)
  title       String?
  periodStart DateTime
  periodEnd   DateTime
  
  // Cached metrics
  totalOfficers  Int @default(0)
  totalUnions    Int @default(0)
  totalMembers   Int @default(0)
  totalLoans     Int @default(0)
  activeLoans    Int @default(0)
  completedLoans Int @default(0)
  defaultedLoans Int @default(0)
  
  totalDisbursed   Decimal @default(0) @db.Decimal(14, 2)
  totalRepaid      Decimal @default(0) @db.Decimal(14, 2)
  totalOutstanding Decimal @default(0) @db.Decimal(14, 2)
  collectionRate   Decimal @default(0) @db.Decimal(5, 2)
  
  // Full snapshot
  reportData     Json?
  officerMetrics Json?
  
  generatedAt DateTime @default(now())
}

Report Types

Available report types:

enum ReportType {
  DAILY
  WEEKLY
  MONTHLY
  QUARTERLY
  CUSTOM
}

Officer Performance Metrics

Reports include per-officer breakdowns:

{
  "officerMetrics": [
    {
      "officerId": "clx...",
      "officerName": "Jane Smith",
      "unionsManaged": 5,
      "totalMembers": 120,
      "loansCreated": 45,
      "totalDisbursed": 4500000.00,
      "totalRepaid": 2800000.00,
      "collectionRate": 92.5,
      "overdueLoans": 3
    }
  ]
}

Viewing Past Reports

Supervisors can retrieve previously generated reports:

// GET /api/supervisor-reports/sessions
// Returns all ReportSession records for the current supervisor

// GET /api/supervisor-reports/sessions/:id
// Returns specific report with full data

Data Access Scope

What Supervisors Can See

Supervisors have visibility into:

Entity	Access Scope
Users	All Credit Officers where `supervisorId` matches current user
Unions	All unions managed by supervised Credit Officers
Members	All members belonging to supervised unions
Loans	All loans created by or assigned to supervised officers
Repayments	All repayments for loans in supervised territory

What Supervisors Cannot See

Supervisors cannot access:

Other supervisors’ territories
System settings and configuration
Admin-only reports
Audit logs for admin actions

Supervisor Permissions Summary

✅ Can Do

Create Credit Officer accounts
Create unions and assign them to officers
View all data in supervised territory
Approve or reject loan applications
Disburse approved loans
Assign/reassign loans to officers
Generate supervisor reports
View officer performance metrics
Record repayments
Manage union members in territory

❌ Cannot Do

Create admin or supervisor accounts
Update or delete unions
Reassign unions to different officers
Delete users
Reset user passwords
Access system configuration
Manage loan types
Enable maintenance mode
Perform backup/restore operations
View other supervisors’ data
Regenerate loan schedules

Best Practices

Regular Territory Reviews

Review your territory’s performance weekly. Look for:

Officers with high overdue rates
Unions with unusual activity
Loans pending approval for too long

Timely Loan Approvals

Review loan applications within 24-48 hours. Delays impact member satisfaction and officer performance.

Clear Rejection Reasons

When rejecting loans, provide specific, actionable feedback. This helps officers improve future applications.

Officer Development

Use report metrics to identify training needs. Officers with low collection rates may need support or coaching.

Territory Balance

Monitor union and member distribution across your officers. Avoid overloading any single officer.

Admin Role

Understand administrator capabilities and system management

Credit Officer Role

Learn about field operations and officer responsibilities

Get Started

Core Features

User Roles

Guides

Core Responsibilities

Supervisor-Officer Hierarchy

Data Model Relationship

Relationship Setup

User Management

Creating Credit Officers

Viewing Team Members

Loan Approval Authority

Approval Workflow

Approving Loans

Rejecting Loans

Loan Disbursement

Loan Assignment

Union Management

Creating Unions

Viewing Supervised Unions

Reporting & Analytics

Supervisor Dashboard

Report Generation

Report Types

Officer Performance Metrics

Viewing Past Reports

Data Access Scope

What Supervisors Can See

What Supervisors Cannot See

Supervisor Permissions Summary

✅ Can Do

❌ Cannot Do

Best Practices

Admin Role

Credit Officer Role

Build docs developers (and LLMs) love

Get Started

Core Features

User Roles

Guides

​Core Responsibilities

​Supervisor-Officer Hierarchy

​Data Model Relationship

​Relationship Setup

​User Management

​Creating Credit Officers

​Viewing Team Members

​Loan Approval Authority

​Approval Workflow

​Approving Loans

​Rejecting Loans

​Loan Disbursement

​Loan Assignment

​Union Management

​Creating Unions

​Viewing Supervised Unions

​Reporting & Analytics

​Supervisor Dashboard

​Report Generation

​Report Types

​Officer Performance Metrics

​Viewing Past Reports

​Data Access Scope

​What Supervisors Can See

​What Supervisors Cannot See

​Supervisor Permissions Summary

​✅ Can Do

​❌ Cannot Do

​Best Practices

​Related Resources

Admin Role

Credit Officer Role

Build docs developers (and LLMs) love

Core Responsibilities

Supervisor-Officer Hierarchy

Data Model Relationship

Relationship Setup

User Management

Creating Credit Officers

Viewing Team Members

Loan Approval Authority

Approval Workflow

Approving Loans

Rejecting Loans

Loan Disbursement

Loan Assignment

Union Management

Creating Unions

Viewing Supervised Unions

Reporting & Analytics

Supervisor Dashboard

Report Generation

Report Types

Officer Performance Metrics

Viewing Past Reports

Data Access Scope

What Supervisors Can See

What Supervisors Cannot See

Supervisor Permissions Summary

✅ Can Do

❌ Cannot Do

Best Practices

Related Resources