Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/IvanchoDev89/maleku-system/llms.txt

Use this file to discover all available pages before exploring further.

Maleku System defines two elevated roles for platform operators: admin and super_admin. Both roles can perform day-to-day platform management tasks, but they operate through different API layers. Admins use the /api/v1/admin/* endpoints (accepting SUPER_ADMIN or ADMIN roles) for vendor oversight, content moderation, and booking management. Super Admins additionally have exclusive access to the /api/v1/superadmin/* endpoints for full user lifecycle control, system configuration, compliance tools, and audit log access. All state-changing actions performed by either role are recorded in a tamper-evident audit log.
The superadmin panel frontend is served at the following routes: /superadmin/analytics, /superadmin/audit, /superadmin/bookings, /superadmin/content, /superadmin/destinations, /superadmin/fleet, /superadmin/reports, /superadmin/reviews, /superadmin/settings, /superadmin/users, and /superadmin/vendors. The API endpoints backing these pages at /api/v1/superadmin/* are all guarded by the require_superadmin() dependency, which enforces an exact super_admin role match.

​
Admin vs Super Admin

Both roles share a large portion of the DEFAULT_ROLE_PERMISSIONS matrix. The practical differences are:
Capabilityadminsuper_admin
Read user list✅✅
Change user roles❌✅
Delete user accounts❌✅
Impersonate users❌✅
Block / unblock users❌✅
Approve vendors✅✅
Suspend / reject vendors❌✅
Manage CMS content✅ (full CRUD + publish)✅ (+ SEO)
View audit logs✅ (system.logs)✅ (+ export)
Export bookings✅✅
Export users / vendors❌✅
System settings & maintenance❌✅
Run compliance checks❌✅
# From app/core/security.py — DEFAULT_ROLE_PERMISSIONS excerpt
"admin": {
    "users":      ["read"],
    "vendors":    ["read", "approve"],
    "bookings":   ["read", "create", "update", "cancel", "export"],
    "content":    ["read", "create", "update", "delete", "publish"],
    "analytics":  ["read", "reports"],
    "system":     ["logs"],
},
"super_admin": {
    "users":      ["create", "read", "update", "delete", "impersonate", "block", "export"],
    "vendors":    ["create", "read", "update", "delete", "approve", "suspend", "export"],
    "system":     ["settings", "maintenance", "backup", "logs", "permissions"],
    # ... full access to all other modules
},
All /api/v1/superadmin/* endpoints require the super_admin role. Requests authenticated with any other role — admin, vendor, agent, customer_service, or client — will receive HTTP 403 Forbidden. There is no fallback or partial access; the require_superadmin() dependency enforces an exact role match.

​
User Management

Super Admins manage the full user lifecycle through the /api/v1/superadmin/users router. Available endpoints:
MethodPathDescription
GET/api/v1/superadmin/usersList all users with filtering and pagination
GET/api/v1/superadmin/users/countGet total user count with optional filters
GET/api/v1/superadmin/users/{user_id}Get detailed profile for a single user
POST/api/v1/superadmin/usersCreate a new user (pre-verified)
PUT/api/v1/superadmin/users/{user_id}Update user fields including role and status
DELETE/api/v1/superadmin/users/{user_id}Permanently delete a user
GET/api/v1/superadmin/users/{user_id}/activityRetrieve audit log history for a user
POST/api/v1/superadmin/users/{user_id}/impersonateGenerate a 1-hour impersonation token
POST/api/v1/superadmin/users/{user_id}/blockSuspend an account (timed or permanent)
POST/api/v1/superadmin/users/{user_id}/unblockReactivate a suspended account
Filtering and sorting on GET /api/v1/superadmin/users supports: search (name or email), role, is_active, is_verified, sort_by, and sort_order. The response payload includes vendor_count and booking_count per user, computed via correlated subqueries for efficiency. Role changes are applied by sending the new role value in the PUT body using the UserUpdateRequest schema: 
class UserUpdateRequest(BaseModel):
    email: EmailStr | None = None
    full_name: str | None = None
    phone: str | None = None
    role: UserRole | None = None      # e.g. UserRole.VENDOR
    is_active: bool | None = None
    is_verified: bool | None = None
Every field change is captured in the audit log with before/after values and a human-readable changes_summary string. Impersonation generates a short-lived (1-hour) access token for the target user. Super Admins cannot impersonate other Super Admins or inactive users. Every impersonation attempt is logged under AuditAction.IMPERSONATE.

​
Vendor Management

The /api/v1/superadmin/vendors router provides full oversight of the vendor lifecycle. Available endpoints:
MethodPathDescription
GET/api/v1/superadmin/vendorsList all vendors with status, search, and sorting filters
GET/api/v1/superadmin/vendors/pendingList vendors awaiting approval with compliance detail
GET/api/v1/superadmin/vendors/{vendor_id}Get detailed vendor profile including stats and compliance flags
POST/api/v1/superadmin/vendors/{vendor_id}/approvalApprove, reject, suspend, or reactivate a vendor
POST/api/v1/superadmin/vendors/{vendor_id}/featureToggle is_featured on a vendor (active vendors only)
GET/api/v1/superadmin/vendors/analytics/overviewPlatform-wide vendor analytics for a configurable date range
POST/api/v1/superadmin/vendors/{vendor_id}/compliance-checkRun a compliance audit on a specific vendor
PUT/api/v1/vendors/{vendor_id}/verifySet is_verified = True (SUPER_ADMIN role required)
PUT/api/v1/vendors/{vendor_id}/activateToggle is_active on a vendor (SUPER_ADMIN role required)
Approval workflow — vendor status transitions are strictly enforced: 
# From app/api/v1/superadmin/vendors.py
valid_transitions = {
    VendorApprovalAction.APPROVE:     ["pending"],
    VendorApprovalAction.REJECT:      ["pending"],
    VendorApprovalAction.SUSPEND:     ["active"],
    VendorApprovalAction.REACTIVATE:  ["suspended"],
}
Attempting an invalid transition (e.g., approving an already-active vendor) returns HTTP 400. All approval actions are written to the audit log with old and new status values. Vendor status values (VendorStatus enum): 
class VendorStatus(str, enum.Enum):
    PENDING   = "pending"
    ACTIVE    = "active"
    SUSPENDED = "suspended"
    REJECTED  = "rejected"

​
Booking Oversight

Admins and Super Admins can view all bookings across every vendor on the platform. The GET /api/v1/superadmin/bookings endpoint supports filtering by vendor, user, status, date range, and listing type, and returns paginated results with full booking detail including vendor and user references. Booking lifecycle statuses (BookingStatus enum): 
class BookingStatus(str, enum.Enum):
    PENDING    = "pending"
    CONFIRMED  = "confirmed"
    CANCELLED  = "cancelled"
    COMPLETED  = "completed"
    REFUNDED   = "refunded"
Admins with the bookings.cancel permission can cancel any booking on the platform. Super Admins additionally hold the bookings.refund permission to process refunds. The booking oversight page in the superadmin panel at /superadmin/bookings surfaces these controls alongside booking analytics.

​
Content Management

The platform ships with a built-in CMS for blog posts and destination pages. Admins control this content through the superadmin panel at /superadmin/content and /superadmin/destinations. Blog posts — managed via GET|POST|PUT|DELETE /api/v1/blog/. Supported publication states follow the BlogPostStatus enum: 
class BlogPostStatus(str, enum.Enum):
    DRAFT      = "draft"
    PUBLISHED  = "published"
    ARCHIVED   = "archived"
Admins can create drafts, publish content, and archive old posts. Super Admins additionally have content.seo permission for managing meta tags and Open Graph data. Destinations — managed via GET|POST|PUT|DELETE /api/v1/destinations/. Destination pages appear in the main navigation and are used for SEO-driven landing pages linking to relevant vendor listings in each geographic area. Both content types support the standard CRUD flow: create as draft, preview, publish, and optionally unpublish back to draft or archive.

​
Audit Logs

Every state-changing operation on the platform is recorded in the audit_logs table via AuditService. The Super Admin can query this log through the /api/v1/superadmin/audit/logs endpoint. Each audit log entry captures:
FieldDescription
user_id / user_emailThe operator who performed the action
actionAuditAction enum value (e.g., create, update, delete, approve, suspend, impersonate, export)
entity_typeThe resource type (e.g., user, vendor, booking, route)
entity_idUUID of the affected record
entity_nameHuman-readable name of the entity
old_values / new_valuesJSON snapshots before and after the change
changes_summaryPlain-language description of what changed
ip_addressRequest origin IP
user_agentBrowser / client string
request_pathAPI path that triggered the event
created_atUTC timestamp
Filtering on GET /api/v1/superadmin/audit/logs supports: user_id, action, entity_type, entity_id, date_from, date_to, and full-text search across changes_summary and entity_name. The platform also maintains a separate security log at GET /api/v1/superadmin/audit/security that records authentication events (login success/failure, account lock/unlock, password changes) with severity levels of info, warning, and critical. A dedicated failed-login monitoring endpoint at GET /api/v1/superadmin/audit/security/failed-logins helps detect brute-force patterns by grouping failures by IP address. Log summary — GET /api/v1/superadmin/audit/summary returns at-a-glance statistics: 
class LogSummary(BaseModel):
    total_audit_logs: int
    total_security_logs: int
    today_audit_logs: int
    today_security_logs: int
    failed_logins_24h: int
    critical_events_24h: int
Export — POST /api/v1/superadmin/audit/export streams audit or security logs in json or csv format (up to 5,000 rows per export), rate-limited to 5 requests per minute. The export action itself is recorded in the audit log.

​
Platform Analytics

The superadmin analytics dashboard at /superadmin/analytics provides a bird’s-eye view of the entire platform. The GET /api/v1/superadmin/vendors/analytics/overview endpoint aggregates:
  • Vendor counts — total, pending approval, active, suspended, and rejected
  • Top performers — up to 10 vendors ranked by revenue, with full VendorStats detail
  • Recent registrations — the 10 most recently created vendor accounts
  • Revenue by vendor type — grouped by business_type (hotel, tour operator, etc.) for the trailing period
  • Bookings by month — a 12-month time series of booking counts and revenue for trend visualisation
The days query parameter (default 30, max 365) controls the date window for trend calculations. All results are computed live from PostgreSQL aggregates.

Build docs developers (and LLMs) love

Get started for freeTalk to us