LlegoYa is a full-stack urban mobility platform for Medellín. The project aims to help public transportation users find routes, track buses, and receive smart travel recommendations through a modern web experience with interactive maps, role-based authentication, and an AI assistant specialized in urban mobility.
The platform is designed as a scalable foundation for a smart mobility ecosystem, where passengers can explore routes and receive recommendations, drivers can share operational information, and administrators can manage routes, buses, and drivers from a centralized system.
The main goal of LlegoYa is to reduce uncertainty when traveling across the city by centralizing information about routes, buses, users, and transportation operations.
The long-term vision includes:
- Route search and comparison.
- Interactive maps with routes and buses.
- AI-powered chatbot for mobility questions in Medellín.
- Management of users, drivers, buses, and routes.
- Dedicated dashboards for passengers, drivers, and administrators.
- A scalable architecture prepared for real-time data, analytics, and future integrations.
The repository currently contains a web-based MVP built with Next.js and TypeScript.
Implemented features include:
- Landing page and authentication flow.
- User registration, login, logout, and token refresh.
- JWT authentication using secure
httpOnlycookies. - Role-based redirection to User, Driver, or Admin dashboards.
- User dashboard with route search, favorites, news, and chatbot.
- Initial administration views for dashboards, routes, drivers, and super administrators.
- Interactive maps using Leaflet with simulated routes and buses across Medellín.
- AI service connected to Ollama for mobility-related questions.
- Prisma data model for users, drivers, vehicles, and routes.
- Database integrations prepared for PostgreSQL (Supabase) and MongoDB.
Some features described throughout the documentation represent the product vision and roadmap, and may not yet be fully implemented in the current version.
LlegoYa supports three main user roles:
- USER – Public transportation passengers. They can search routes, use the AI chatbot, manage favorites, and review travel history.
- DRIVER – Drivers who can view assigned routes and share operational status or location.
- SUPER_ADMIN – Administrators responsible for managing routes, drivers, buses, and operational information.
| Category | Technology |
|---|---|
| Framework | Next.js 16 (App Router) |
| Language | TypeScript |
| UI | React 19, Tailwind CSS 4, Radix UI, Lucide React |
| Maps | Leaflet, React Leaflet |
| Database | PostgreSQL with Prisma 7 and @prisma/adapter-pg |
| External Services | Supabase Client, MongoDB Client |
| Authentication | JWT (jose), httpOnly cookies, bcryptjs |
| AI | Ollama (local AI service) |
| Code Quality | ESLint, Prettier, Husky, lint-staged |
.
├── documentation/ # Product documentation (ES/EN)
├── prisma/ # Prisma schema and database configuration
├── public/ # Static assets
├── src/
│ ├── app/ # Next.js routes, layouts, and API routes
│ ├── components/ # Reusable UI components
│ ├── generated/ # Generated Prisma Client
│ ├── lib/ # Authentication, maps, clients, and utilities
│ ├── modules/ # Domain modules (auth, routes, user, shared)
│ ├── shared/ # Shared types, validators, and constants
│ └── types/ # Global TypeScript types
├── ARQUITECTURA.md # Architecture notes
├── TOKENS.md # Authentication and token documentation
└── package.json
The authentication module is mainly located in:
src/modules/authsrc/lib/auth.tssrc/middleware.tssrc/app/api/auth
Features include:
- User registration and login
- Password hashing
- Access and refresh tokens
- Secure
httpOnlycookies - Route protection middleware
- Role-based redirection after login
The user module is located in src/modules/user and includes:
- User dashboard
- Route search
- Favorite routes
- News section
- AI chatbot
Located in:
src/modules/routessrc/lib/maps
It uses Leaflet to display:
- Medellín city map
- Simulated transportation routes
- Simulated buses
- Geographic boundaries
The AI service is located in:
src/modules/shared/services/ai.service.ts
It connects to Ollama using a system prompt focused exclusively on urban mobility in the Aburrá Valley.
Related environment variables:
OLLAMA_ENDPOINTOLLAMA_MODEL
The main relational schema is defined in:
prisma/schema.prisma
Current entities include:
usersdriverstransportsroutesuser_role
Before running the project, make sure you have:
- Node.js compatible with Next.js 16
- npm
- PostgreSQL configured through
DATABASE_URL - Ollama installed and running (optional, required for the AI chatbot)
- MongoDB (optional, for logging and future AI features)
- Supabase credentials (optional)
Create a .env file in the project root.
DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE"
JWT_SECRET="replace-with-a-secure-secret"
JWT_REFRESH_SECRET="replace-with-a-secure-refresh-secret"
ACCESS_TOKEN_EXPIRES_IN="15m"
REFRESH_TOKEN_EXPIRES_IN="7d"
OLLAMA_ENDPOINT="http://127.0.0.1:11434/api"
OLLAMA_MODEL="smartops-bot"
MONGODB_URI="mongodb+srv://USER:PASSWORD@HOST/DATABASE"
NEXT_PUBLIC_SUPABASE_URL="https://your-project.supabase.co"
NEXT_PUBLIC_SUPABASE_ANON_KEY="your-anon-key"For local development, the most important variables are:
DATABASE_URLJWT_SECRETJWT_REFRESH_SECRET
MongoDB, Supabase, and Ollama are only required if you want to test those specific features.
Install dependencies:
npm installGenerate the Prisma Client:
npm run db:generateSynchronize the database schema:
npm run db:pushStart the development server:
npm run devThe application will usually be available at:
http://localhost:3000
npm run dev # Start development server
npm run build # Build for production
npm run start # Run production build
npm run lint # Run ESLint
npm run format # Format code with Prettier
npm run db:generate # Generate Prisma Client
npm run db:push # Synchronize Prisma schema| Route | Description |
|---|---|
/ |
Landing page |
/login |
Login page |
/register |
User registration |
/user |
User dashboard |
/driver |
Driver dashboard |
/admin |
Admin dashboard |
/admin/routes |
Route management |
/admin/driver |
Driver management |
/admin/superadmin |
Super administrator panel |
/api/auth/* |
Authentication endpoints |
/api/chat |
AI chatbot endpoint |
- Use strict TypeScript and avoid
any. - Keep UI, business logic, data access, and types separated by module.
- Prefer reusable components inside
src/componentsor the corresponding module. - Store shared validation logic in
src/shared/validators. - Run linting and formatting before opening a Pull Request.
- Never commit real secrets or sensitive environment variables.
- Contribute through Pull Requests targeting protected branches.
Functional and organizational documentation is available in the documentation/ directory.
Spanish:
documentation/ES/PRODUCT_VISION.mddocumentation/ES/PROJECT-OVERVIEW.mddocumentation/ES/USER_ROLES.mddocumentation/ES/SPRINT_PLANNING.mddocumentation/ES/RESPONSABILITIES.md
English versions are also available in:
documentation/EN/
Planned future features include:
- Real-time GPS tracking for buses and drivers.
- Complete management of routes, vehicles, and assignments.
- Persistent route history and favorite routes.
- Smart service disruption alerts.
- Data-driven travel recommendations.
- RAG integration to provide up-to-date operational information.
- Analytics dashboards for transportation companies and administrators.
- Mobile application.
This project is private and intended for academic and professional use by the LlegoYa development team, unless a different license is specified in the repository.