Executive Summary
Lucy is Ethiopia's full-stack freelance connect and match platform. It connects Hire Clients who post jobs with Freelancers who apply using connects. The platform includes AI-powered job matching, structured hiring pipelines, moderated messaging, contract workflows, local ETB payments via Telebirr and Ethiopian banks, identity verification, social feed and stories, Telegram bot access, and multilingual support (English, Amharic, and Oromiffa in the app).
Production
https://jobs.lucyhub.org | API: /api | Swagger: /api/docs | Contact: partnerships@lucyhub.org
Platform Architecture
| Layer | Technology | Notes |
|---|---|---|
| Frontend | Next.js 15 (React) | Port 3000, App Router, SSR/CSR |
| Backend API | NestJS 11 | Port 3001, prefix /api |
| Database | MongoDB Atlas | Document store, Mongoose ODM |
| Real-time | Socket.IO | Chat and live notifications |
| AI | OpenAI-compatible LLM | Job matching, cover letters, assistant |
| Payments | Telebirr + 20+ banks | Manual verification workflow |
| Bot | Telegram (Telegraf) | Full marketplace in Telegram |
| i18n | EN | AM | OM | API and UI localization |
Browser and Telegram clients connect through nginx (SSL) to Next.js on port 3000 and NestJS API on port 3001, backed by MongoDB Atlas. Real-time chat uses Socket.IO. AI providers connect via OpenAI-compatible APIs.
- apps/api - NestJS REST API, feature modules, seeds, schedulers
- apps/web - Next.js frontend, dashboards, public pages, admin panels
- docs/ - Deployment guides (VPS, Render)
- scripts/ - Deployment, translation, and utility scripts
User Roles and Dashboards
| Role | Dashboard | Key Capabilities |
|---|---|---|
| Freelancer (Talent) | /freelancer | AI job matching, applications, contracts, wallet, profile, QR card |
| Hire Client | /client | Post jobs, talent discovery, hiring pipeline, billing, companies |
| Admin | /admin | Operations, payments, disputes, moderation |
| Superadmin | /superadmin | Platform settings, commissions, broadcasts |
Dual profiles
One account can hold both Freelancer and Hire Client roles with separate profiles, switchable in the web app and Telegram bot.
Core Marketplace Flows
Hire Client journey: post a job (4-step wizard), manage subscription quota, discover talent, run the pipeline Kanban (Applied to Hired), pay the contract offer, and track billing.
Freelancer journey: browse AI-ranked jobs (Best Match, Recent, All), apply with connects, accept invites for free, chat with contact masking until offer is paid, deliver milestones, and build a public profile with reviews.
Feature Modules
| Module | Description |
|---|---|
| AI Matching | Heuristic scoring + optional LLM rerank and cover letter drafts |
| Contracts | Milestones, delivery, disputes, auto-review scheduler |
| Commission | Percent-based hire commission; client and talent dues |
| Connects | Application credits; wallet and purchase flows |
| Subscriptions | Client plans: Free, Premium Family, Monthly, Yearly, Enterprise |
| Chat | Moderated messaging, contact masking, Socket.IO gateway |
| Social Feed | Posts, likes, comments, stories |
| Follow System | Followers, following, requests, privacy controls |
| Verification | National ID / Fayda identity verification |
| Telegram Bot | Jobs, hire, contracts, wallet, profile, dual-role switching |
| AI Assistant | Lucy AI chat with token wallet and RAG knowledge base |
| Analytics | Admin operations metrics and reporting |
| Referrals | Referral rewards and signup tracking |
Telegram Bot
The Lucy Telegram bot provides full marketplace access without installing the web app. Users link their account via email OTP. The bot supports English, Amharic, and Oromiffa.
- Freelancers: browse jobs, apply, contracts, wallet, profile, role switching
- Hire clients: post jobs, pipeline, find talent, invites, commission payments
- Shared: feed shortcuts, messages, notifications, web deep links
Payments and Monetization
- Telebirr (Ethio Telecom mobile money)
- Major Ethiopian banks: CBE, Awash, Dashen, Abyssinia, Hibret, and 15+ more
- Hire commission (configurable % of contract offer)
- Connect packs, subscriptions, Premium Family, AI tokens
| Plan | Price (ETB) | Job Posts | Companies | Stories/Day |
|---|---|---|---|---|
| Free | 0 | 3 / month | 1 | 1 |
| Premium Family | 199 / mo | 3 / month | 1 | Unlimited |
| Client Monthly | 499 / mo | Unlimited | 5 | 1 |
| Client Yearly | 4,999 / yr | Unlimited | 10 | 1 |
| Client Enterprise | 14,999 / yr | Unlimited | Unlimited | Unlimited |
API Overview
| Module | Key Endpoints |
|---|---|
| Categories | GET /api/categories?lang=en|am|om |
| Jobs | CRUD, search, geo filters, expiry scheduler |
| Matching | GET /api/matching/jobs, explain, talent search |
| Applications | Apply, pipeline status, interviews, offers |
| Contracts | Pay, milestones, delivery, disputes |
| Payments | Checkout, commission payments, wallet deposits |
| Chat | Conversations, messages, moderation |
| Posts | Feed posts, stories, likes, comments |
| Follow | Follow, unfollow, requests, privacy |
| Talent | Public profiles, search, reviews |
| Telegram | Webhook, account linking, OTP auth |
Admin and Operations
| Console | Path | Capabilities |
|---|---|---|
| /admin | Operations | Payments, disputes, users, moderation, analytics |
| /superadmin | Platform | Commission rates, broadcasts, settings, seeds |
| Commission tab | /admin/payments | Job summary, offer %, approve/reject |
| Subscriptions | Admin review | Telebirr/bank payment verification |
- Commission suspension blocks marketplace actions until dues are paid
- Email templates for hiring, commission, follow, and verification events
- Scheduled jobs: contract review, job expiry, commission recalculation
Security and Compliance
- JWT authentication with role-based access control (RBAC)
- Commission suspension guard for unpaid platform dues
- Contact masking in chat until contract payment
- National ID verification (Fayda) for trusted profiles
- Admin moderation for chat, payments, and disputes
- Rate limiting on sensitive endpoints (OTP, auth)
Deployment Guide
- Production: Docker Compose on VPS (nginx reverse proxy, SSL via Certbot)
- Web container on port 3000, API on port 3001
- MongoDB Atlas for production database
- Deploy script: scripts/deploy-vps.sh
- Local dev: npm install && npm run dev
- Docker dev: docker compose -f docker-compose.dev.yml up --build