# kheangsenghorng/smartpos_identity-service architecture

> Architecture diagram of the GitHub repository kheangsenghorng/smartpos_identity-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kheangsenghorng/smartpos_identity-service
- Repository: https://github.com/kheangsenghorng/smartpos_identity-service

## Overview

SmartPOS Identity Service provides authentication, account management, RBAC, POS PIN verification, and device/session security through a versioned API. The main workflow starts with a client request, passes through Laravel routing and authentication, then performs the requested identity operation and returns a response; the graph also preserves the service’s authorization, audit, email-verification, and profile capabilities. Evidence is limited to the README, source index references, and shown excerpts; several documented subsystems have unsampled implementations.

Main entry points: [`app/Http/Controllers/Api/AuthController.php`](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/AuthController.php) (Authentication), [`app/Models/User.php`](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Models/User.php) (User accounts), [`app/Models/Role.php`](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Models/Role.php) (Roles), [`app/Services/RbacCacheService.php`](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Services/RbacCacheService.php) (RBAC cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API entry"]
  node_routing["API routes<br/>[api.php]"]
  node_auth_routes["Auth routes<br/>[auth.php]"]
end

subgraph group_identity["Identity workflows"]
  node_auth["Authentication<br/>[AuthController.php]"]
  node_users_api["User management<br/>[UserController.php]"]
  node_user[("User accounts<br/>[User.php]")]
  node_email_change["Email change"]
  node_email_verify["Email verification"]
  node_email_mail["Verification mail"]
  node_pin["POS PIN"]
end

subgraph group_access["Access control"]
  node_role_api["Role management<br/>[RoleController.php]"]
  node_permission_api["Permission management"]
  node_roles[("Roles<br/>[Role.php]")]
  node_permissions[("Permissions<br/>[Permission.php]")]
  node_rbac_cache["RBAC cache"]
  node_role_provision["Role provisioning"]
end

subgraph group_security["Session security"]
  node_sessions_api["Session management"]
  node_sessions[("User sessions<br/>[UserSession.php]")]
  node_devices_api["Device management"]
  node_devices[("User devices<br/>[UserDevice.php]")]
end

subgraph group_support["Audit and profile"]
  node_login_audit["Login audit"]
  node_security_events["Security events"]
  node_avatar["Avatar processing<br/>[AvatarService.php]"]
end

node_client(("API client"))

node_client -->|"sends request"| node_routing
node_routing -->|"routes auth"| node_auth_routes
node_auth_routes -->|"dispatches to"| node_auth
node_auth -->|"authenticates"| node_user
node_auth -->|"finds or creates"| node_devices
node_auth -->|"manages sessions"| node_sessions
node_auth -->|"records events"| node_security_events
node_users_api -->|"manages accounts"| node_user
node_users_api -->|"processes uploads"| node_avatar
node_email_change -->|"updates pending email"| node_user
node_email_change -->|"sends verification"| node_email_mail
node_email_verify -->|"verifies address"| node_user
node_pin -.->|"serves PIN workflow"| node_user
node_role_api -.->|"manages roles"| node_roles
node_permission_api -.->|"manages permissions"| node_permissions
node_roles -->|"attaches permissions"| node_permissions
node_user -->|"checks access"| node_rbac_cache
node_rbac_cache -->|"reads role data"| node_roles
node_role_provision -->|"invalidates cache"| node_rbac_cache
node_sessions_api -->|"lists and revokes"| node_sessions
node_devices_api -.->|"manages devices"| node_devices
node_login_audit -.->|"exposes audit"| node_security_events
node_auth -->|"records attempts"| node_login_audit

click node_routing "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/routes/api.php"
click node_auth_routes "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/routes/api/auth.php"
click node_auth "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/AuthController.php"
click node_users_api "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/UserController.php"
click node_user "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Models/User.php"
click node_email_change "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/EmailChangeController.php"
click node_email_verify "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/EmailVerificationController.php"
click node_email_mail "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Mail/EmailChangeVerificationMail.php"
click node_pin "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/UserPosPinController.php"
click node_role_api "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/RoleController.php"
click node_permission_api "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/PermissionController.php"
click node_roles "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Models/Role.php"
click node_permissions "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Models/Permission.php"
click node_rbac_cache "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Services/RbacCacheService.php"
click node_role_provision "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Services/RoleProvisionService.php"
click node_sessions_api "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/UserSessionController.php"
click node_sessions "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Models/UserSession.php"
click node_devices_api "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/UserDeviceController.php"
click node_devices "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Models/UserDevice.php"
click node_login_audit "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/LoginAttemptController.php"
click node_security_events "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Services/SecurityEventService.php"
click node_avatar "https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Services/AvatarService.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_routing,node_auth_routes,node_client toneBlue
class node_auth,node_users_api,node_user,node_email_change,node_email_verify,node_email_mail,node_pin toneAmber
class node_role_api,node_permission_api,node_roles,node_permissions,node_rbac_cache,node_role_provision toneMint
class node_sessions_api,node_sessions,node_devices_api,node_devices toneRose
class node_login_audit,node_security_events,node_avatar toneIndigo
```

## Components

### API entry

- [API routes](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/routes/api.php): `routes/api.php`
- [Auth routes](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/routes/api/auth.php): `routes/api/auth.php`

### Identity workflows

- [Authentication](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/AuthController.php): `app/Http/Controllers/Api/AuthController.php`
- [User management](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/UserController.php): `app/Http/Controllers/Api/UserController.php`
- [User accounts](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Models/User.php): `app/Models/User.php`
- [Email change](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/EmailChangeController.php): `app/Http/Controllers/Api/EmailChangeController.php`
- [Email verification](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/EmailVerificationController.php): `app/Http/Controllers/Api/EmailVerificationController.php`
- [Verification mail](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Mail/EmailChangeVerificationMail.php): `app/Mail/EmailChangeVerificationMail.php`
- [POS PIN](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/UserPosPinController.php): `app/Http/Controllers/Api/UserPosPinController.php`

### Access control

- [Role management](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/RoleController.php): `app/Http/Controllers/Api/RoleController.php`
- [Permission management](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/PermissionController.php): `app/Http/Controllers/Api/PermissionController.php`
- [Roles](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Models/Role.php): `app/Models/Role.php`
- [Permissions](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Models/Permission.php): `app/Models/Permission.php`
- [RBAC cache](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Services/RbacCacheService.php): `app/Services/RbacCacheService.php`
- [Role provisioning](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Services/RoleProvisionService.php): `app/Services/RoleProvisionService.php`

### Session security

- [Session management](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/UserSessionController.php): `app/Http/Controllers/Api/UserSessionController.php`
- [User sessions](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Models/UserSession.php): `app/Models/UserSession.php`
- [Device management](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/UserDeviceController.php): `app/Http/Controllers/Api/UserDeviceController.php`
- [User devices](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Models/UserDevice.php): `app/Models/UserDevice.php`

### Audit and profile

- [Login audit](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Http/Controllers/Api/LoginAttemptController.php): `app/Http/Controllers/Api/LoginAttemptController.php`
- [Security events](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Services/SecurityEventService.php): `app/Services/SecurityEventService.php`
- [Avatar processing](https://github.com/kheangsenghorng/smartpos_identity-service/blob/master/app/Services/AvatarService.php): `app/Services/AvatarService.php`

### Other components

- **API client**

## Connections

- API client → API routes: sends request
- API routes → Auth routes: routes auth (evidence: `routes/api/auth.php`)
- Auth routes → Authentication: dispatches to (evidence: `routes/api/auth.php`)
- Authentication → User accounts: authenticates (evidence: `app/Http/Controllers/Api/AuthController.php`)
- Authentication → User devices: finds or creates (evidence: `app/Http/Controllers/Api/AuthController.php`)
- Authentication → User sessions: manages sessions (evidence: `app/Http/Controllers/Api/AuthController.php`)
- Authentication → Security events: records events (evidence: `app/Http/Controllers/Api/AuthController.php`)
- User management → User accounts: manages accounts
- User management → Avatar processing: processes uploads
- Email change → User accounts: updates pending email (evidence: `app/Http/Controllers/Api/EmailChangeController.php`)
- Email change → Verification mail: sends verification (evidence: `app/Http/Controllers/Api/EmailChangeController.php`)
- Email verification → User accounts: verifies address (evidence: `app/Http/Controllers/Api/EmailVerificationController.php`)
- POS PIN → User accounts: serves PIN workflow
- Role management → Roles: manages roles
- Permission management → Permissions: manages permissions
- Roles → Permissions: attaches permissions (evidence: `app/Models/Role.php`)
- User accounts → RBAC cache: checks access (evidence: `app/Models/User.php`)
- RBAC cache → Roles: reads role data (evidence: `app/Services/RbacCacheService.php`)
- Role provisioning → RBAC cache: invalidates cache (evidence: `app/Services/RoleProvisionService.php`)
- Session management → User sessions: lists and revokes (evidence: `app/Http/Controllers/Api/UserSessionController.php`)
- Device management → User devices: manages devices
- Login audit → Security events: exposes audit
- Authentication → Login audit: records attempts (evidence: `app/Http/Controllers/Api/AuthController.php`)
