Maleku System is a production-ready, full-stack multi-vendor tourism marketplace built specifically for Costa Rica. It connects travellers with local vendors who offer hotels, tours, vehicle rentals, boat charters, and domestic flights — all on a single platform. Vendors self-manage their listings through a dedicated dashboard while administrators oversee the entire marketplace through a layered role-based access control (RBAC) system. The platform solves the fragmentation problem in Costa Rican tourism by giving vendors a unified storefront, giving clients a trusted booking engine with Stripe-powered payments, and giving administrators full visibility through audit logs and analytics.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.
Quickstart
Run the full stack locally with Docker Compose and make your first authenticated API request in under five minutes.
Architecture
Explore the layered system design: Nuxt.js frontend, FastAPI backend, PostgreSQL, Redis, and Cloudinary.
API Reference
Browse every REST endpoint — auth, vendors, bookings, search, Stripe webhooks, and more.
Vendor Guide
Learn how to register as a vendor, publish listings, manage availability, and track commissions.
User Roles
Maleku System enforces six distinct roles across the entire stack (backend RBAC + frontend route middleware). Each role carries a specific set of permissions that cannot be escalated without an explicit admin action.| Role | Description |
|---|---|
| Super Admin | Full platform control — manages all users, vendors, bookings, audit logs, and platform-level settings via /api/v1/superadmin. Can view all content and override any record. |
| Admin | Manages the vendor ecosystem — approves vendor applications, verifies vendor profiles, runs email marketing campaigns, and maintains the blog and destinations CMS. |
| Agent | Internal staff role with elevated read and write access across bookings and customer data, used for customer-facing operations support. |
| Customer Service | Internal support role scoped to handling customer inquiries, reviewing booking disputes, and assisting with account issues. |
| Vendor | Registers a business profile and publishes listings (properties, tours, vehicles, boats, flights). Accesses a personal dashboard with availability calendars, booking history, and commission reporting. |
| Client | Browses listings, makes bookings, processes payments through Stripe Checkout, leaves reviews, and manages their trip planner. |
Key Capabilities
Multi-Vendor Marketplace
Vendors independently manage five listing types — hotels/properties, tours, vehicle rentals, boat charters, and domestic flights — each with its own availability calendar, pricing rules, and JSONB-stored amenities.Booking Engine
A dedicated booking service handles availability checks, createsPENDING reservations, and upgrades them to CONFIRMED only after a successful Stripe webhook confirmation. Clients can cancel bookings through PUT /api/v1/bookings/{id}/cancel.
Stripe Payments
End-to-end payment processing via Stripe Checkout with webhook verification. A configurable commission rate (default 10 %) is calculated on every successful payment and attributed to the platform. TheSTRIPE_COMMISSION_RATE setting in backend/.env controls the split.
JWT Authentication & RBAC
Stateless authentication uses short-lived access tokens (60 minutes) and refresh tokens (7 days), both signed with HS256. A Redis-backed token blacklist invalidates tokens immediately on logout. Passwords are hashed with bcrypt (12 salt rounds) and accounts are locked for 15 minutes after five failed login attempts.Full-Text Search
PostgreSQLtsvector columns with GIN indexes power weighted full-text search across listing names, descriptions, and locations. Results are filterable by type (properties, tours, vehicles, etc.) and renderable on an interactive Leaflet map via GET /api/v1/search/map.
Internationalisation (ES / EN / FR)
The Nuxt.js frontend ships with translation files for Spanish, English, and French. Language detection and switching are handled transparently by the i18n module without server-side route changes.Audit Logging
Every significant write operation is recorded and exposed atGET /api/v1/superadmin/audit. Combined with soft-delete (deleted_at timestamps on all models), the platform maintains a full history of changes for compliance and support purposes.
Maleku System is released under the MIT License © 2024 Costa Rica Travel. You are free to use, modify, and distribute it for any purpose, including commercial projects, with no warranty provided.