Core Module
The Core module provides foundational functionality for IOTA SDK platform. Every application built on the SDK requires this module.
Purpose
The Core module handles:
- User authentication and authorization
- Role-based access control (RBAC)
- File uploads and management
- Session management
- Currency definitions
- Tenant management (in multi-tenant mode)
Key Concepts
User
Central entity representing platform users. Users can:
- Authenticate via username/password
- Have multiple roles assigned
- Belong to groups for organization
- Upload avatars and files
- Be blocked/deactivated
Role
Defines a set of permissions. The RBAC system allows:
- Granular permission control
- Role inheritance
- Dynamic permission checks
- Module-specific permissions
Session
Cookie-based session management:
- Secure session storage (DB-backed)
- Automatic expiration (configurable via
SESSION_DURATION) - Expired sessions are rejected on authorize and removed from storage
- Multi-device support
- Session invalidation
Upload
File upload handling with:
- Hash-based storage (deduplication)
- Size and type validation
- Multiple upload support
- Secure file serving
Architecture
Components
Users
User management including:
- Profile management
- Password management (bcrypt hashed)
- Avatar uploads
- Account blocking
- UI language preferences
Relationships:
Roles
Role management with:
- Permission assignments
- User role assignment
- System and custom roles
Groups
User grouping for:
- Organizational structure
- Bulk operations
- Reporting hierarchies
Settings
System configuration:
- Application settings
- Tenant-specific overrides
- Localization defaults
Dashboard
Main dashboard view with:
- Quick actions
- Recent activity
- Navigation shortcuts
Account
User self-service:
- Profile editing
- Password changes
- Language selection
API Reference
GraphQL Schema
The Core module exposes GraphQL endpoints:
| Type | Queries | Mutations |
|---|---|---|
| User | user, users | (use REST /users for create/update/delete) |
| Upload | upload, uploads | uploadFile, uploadFileWithSlug |
| Auth | — | authenticate(email!, password!) → Session! (logout via REST GET /logout) |
| Session | — | deleteSession(token: String!) (resolver may be unimplemented) |
See API Reference for detailed schema documentation.
REST Endpoints
Standard REST endpoints for form submissions:
| Endpoint | Method | Purpose |
|---|---|---|
/health | GET | Liveness probe (JSON {"status":"healthy"}); checks DB and Spotlight readiness. No auth. |
/users | GET | List users |
/users | POST | Create user |
/users/:id | GET | View user |
/users/:id | POST | Update user |
/users/:id | DELETE | Delete user |
/login | POST | Authenticate |
/logout | GET | End session |
When the application registers them, the Core module also provides optional detailed health and system info UI (authenticated):
| Endpoint | Method | Purpose |
|---|---|---|
/system/health | GET | Detailed health (JSON, capabilities). Requires auth. |
/system/info | GET | System information and metrics UI (HTML). Requires auth. |
/system/info/metrics | GET | Metrics partial (HTMX). Requires auth. |
Additional Core REST routes (when registered): /spotlight/search (GET, search); /uploads (POST, form uploads); /api/uploads (POST, when upload API enabled via ModuleOptions); /roles, /groups (CRUD); /account, /account/sessions (profile and session management); /settings/sessions (admin session list/revoke); /login/2fa/setup, /login/2fa/verify, /login/2fa/verify/recovery, /login/2fa/verify/resend (2FA when enabled).
Permissions
Available Permissions
| Permission | Description |
|---|---|
User.Read | View user list and details |
User.Create | Create new users |
User.Update | Modify existing users |
User.Delete | Remove users |
User.UpdateBlockStatus | Block or unblock user |
Role.Read | View roles |
Role.Create | Create roles |
Role.Update | Modify roles |
Role.Delete | Delete roles |
Group.Read | View groups |
Group.Create | Create groups |
Group.Update | Modify groups |
Group.Delete | Delete groups |
Upload.Read | View uploads |
Upload.Create | Upload files |
Upload.Update | Update upload metadata |
Upload.Delete | Delete uploads |
Session.Read | View sessions (admin) |
Session.Delete | Revoke sessions |
Default Roles
| Role | Permissions |
|---|---|
| Superadmin | All permissions |
| Admin | Users, roles, settings management |
| Manager | View users, limited edit |
| User | View own profile only |
When an authenticated user lacks the required permission for a resource, the framework returns 403 Forbidden and can render a dedicated forbidden page instead of redirecting to login.
Integration with Other Modules
Service Access
Other modules access Core services by declaring them as constructor parameters. The reflection injector resolves each parameter from the composition container by type, so there is no explicit lookup ceremony:
// modules/finance/component.go
composition.ProvideFunc(builder, services.NewExpenseService) // takes *UserService, upload.Repository, ...Shared Entities
Core entities used across modules:
| Entity | Usage |
|---|---|
| User | Created by, assigned to, approved by |
| Upload | Attachments, avatars, documents |
| Currency | Financial transactions |
| Role | Permission checks |
Events
The Core module publishes domain events:
| Event | Description |
|---|---|
UserCreated | New user registered |
UserUpdated | User profile changed |
UserPasswordChanged | Password updated |
UserBlocked | User deactivated |
RoleAssigned | Role given to user |
UploadCreated | File uploaded |
Configuration
Module Options
Configure during registration via core.ModuleOptions (passed to core.NewComponent(opts)):
- Permission Schema - Define available permissions (e.g. for Roles UI).
- LoginControllerOptions - Customize middleware or access checks for login routes (e.g. custom “login gate”).
- DashboardLinkPermissions - Permissions required to see the Dashboard link in the sidebar; if empty, default visibility applies.
- SettingsLinkPermissions - Permissions required to see the Settings link in the sidebar.
- UploadsAuthorizer / DefaultTenantID - For upload API when using API-based uploads.
The sidebar shows navigation items only to users who have at least one role; users with no roles see no sidebar nav items. The Settings link defaults to /settings/logo.
Environment Variables
| Variable | Purpose |
|---|---|
SESSION_DURATION | Session duration |
SID_COOKIE_KEY | Session cookie name |
MAX_UPLOAD_SIZE | File upload size limit |
MAX_UPLOAD_MEMORY | Multipart form memory limit (bytes) |
UPLOADS_PATH | File storage directory |
Usage
The Core component is included in modules.Components() and is usually loaded by registering the full component list with composition.NewEngine(), then compiling with the capabilities your process needs.
Best Practices
- Always check permissions - Use middleware for route protection
- Validate uploads - Check file types and sizes
- Hash passwords - Never store plain text passwords
- Use events - Subscribe to user events for integrations
- Session security - Rotate session IDs on privilege change
Next Steps
- Finance Module - Financial management
- Architecture - Understanding DDD patterns