Actor Identification Methodology

Types of Actors

Actors are people or systems that interact with your systems.

1. User Actors (People)

Questions to ask:

Who uses this system?
What user roles exist?
What are the personas?
What permissions do they have?

Common user actors:

End User / Customer - Primary users of customer-facing systems
Administrator - System administrators, super users
Support Agent - Customer support representatives
Developer - Internal developers using APIs
Manager - Business users viewing reports
Guest / Anonymous User - Unauthenticated visitors

How to identify:

Look for authentication/authorization code
Check user role definitions in code
Review database user/role tables
Analyze permission systems

Code indicators:

// User roles indicate actors
enum UserRole {
  CUSTOMER,      // → Customer actor
  ADMIN,         // → Administrator actor
  SUPPORT,       // → Support Agent actor
  GUEST          // → Anonymous User actor
}

2. External System Actors

Questions to ask:

What external services are integrated?
What third-party APIs are called?
What systems are outside our control?
What services do we depend on?

Common external system actors:

Payment Providers - Stripe, PayPal, Square
Email Services - SendGrid, Mailgun, AWS SES
SMS Services - Twilio, Nexmo
Authentication Providers - Auth0, Okta, Firebase Auth
Analytics Services - Google Analytics, Mixpanel
CDN Services - CloudFront, Cloudflare
Cloud Storage - AWS S3, Google Cloud Storage
Monitoring Services - Datadog, New Relic, Sentry

How to identify:

Search for API keys in config files (.env.example)
Check package dependencies for SDK libraries
Review environment variables
Look for external API base URLs

Example external actors:

# .env.example reveals external actors:
STRIPE_API_KEY=sk_test_...        # → Stripe actor
SENDGRID_API_KEY=SG...            # → SendGrid actor
TWILIO_ACCOUNT_SID=AC...          # → Twilio actor
GOOGLE_ANALYTICS_ID=UA-...        # → Google Analytics actor

Actor Documentation Format

{
  "actors": [
    {
      "id": "customer",
      "name": "Customer",
      "type": "user",
      "description": "End user who browses products and makes purchases",
      "interacts_with": ["customer-web-app", "mobile-app"]
    },
    {
      "id": "stripe",
      "name": "Stripe Payment Gateway",
      "type": "external-actor",
      "description": "Third-party payment processing service",
      "interacts_with": ["payment-api"]
    }
  ]
}

Search Commands for Actors

Find user roles:

grep -r "role\|Role\|USER_ROLE\|UserRole" src/
grep -r "permissions\|Permissions" src/
grep -r "enum.*Role\|class.*Role" src/

Find external integrations:

cat .env.example | grep -E "API_KEY|API_URL|WEBHOOK|TOKEN"
grep -r "stripe\|sendgrid\|twilio\|auth0" package.json
grep -r "import.*stripe\|from.*sendgrid" src/

Find authentication code:

grep -r "auth\|Auth\|authentication\|login" src/
grep -r "jwt\|JWT\|oauth\|OAuth" src/

3.1 KiB Raw Blame History