Tuklas (Filipino, /tuːklɑːs/) — to discover, to uncover, to find.
Tuklas is a high-performance, semi-automated job hunting assistant built for the Philippine and Southeast Asian job markets. It solves the fragmentation of job discovery by ingesting listings from JSearch (Google for Jobs), LinkedIn, JobStreet, and Indeed into a unified, brutalist dashboard.
v1 — SaaS-Ready Personal Assistant. v2 — Multi-tenant Job Discovery Ecosystem.
The hosted product lives at tuklas.dev. Staging is available at tuklasjobs.vercel.app.
- Unified Ingestion Engine: Parses job alert emails (Gmail API + Pub/Sub) and fetches live listings via JSearch API.
- Interactive Demo Sandbox: Experience the full flow (Discovery, Tracker, Logs) entirely client-side at
/demo. - BYOK (Bring Your Own Key): Users can provide their own RapidAPI or LLM keys to bypass server-side quotas.
- Admin Dashboard: Centralized management for Global AI keys (Gemini, OpenRouter), rate limits, and system telemetry.
- Tailored AI Cover Letters: Generates personalized applications using cloud-based LLMs with user-customizable prompts.
- Bulk Action System: High-performance management for review queues and application status tracking.
- Security-First Architecture: 32-byte AES-256-GCM envelope encryption for all third-party secrets.
- Compliance Ready: Built-in Consent Intercept for RA 10173 (Data Privacy Act) compliance.
| Layer | Technology |
|---|---|
| Framework | Next.js 16 (App Router) |
| UI Library | React 19 + Framer Motion |
| Styling | Tailwind CSS 4 |
| Database | Supabase (Postgres) + Redis (Upstash) |
| Authentication | Supabase Auth + Google OAuth |
| AI / LLM | Google Gemini 2.0 Flash / OpenRouter |
| Security | AES-256-GCM Encryption + Upstash Rate Limiting |
- Node.js 22+
- Supabase Project
- Upstash Redis Instance
- (Optional) RapidAPI account for JSearch ingestion
npm install
cp .env.example .env.local # fill in required values
supabase db push
npm run devImportant
ENCRYPTION_KEY: You must provide a valid 32-byte hex string (64 characters) in your .env.local. This is critical for the "Encryption Engine" that protects your API secrets.
How to generate one:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
Tuklas is designed with a Defense-in-Depth posture:
- Zero-Plaintext Policy: Production builds fail immediately if
ENCRYPTION_KEYis missing. All credentials are encrypted before storage. - Just-in-Time Consent: Sensitive data transmission (e.g., sending CV text to AI) requires explicit user confirmation.
- Tenant Isolation: All database reads are scoped by
user_idat both the application and RLS layers. - Server-Side Masking: Secrets are masked on the server; the UI never receives raw API keys.
| Variable | Required | Description |
|---|---|---|
NEXT_PUBLIC_SUPABASE_URL |
Yes | Supabase project URL |
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY |
Yes | Supabase publishable key |
SUPABASE_SERVICE_ROLE_KEY |
Yes | Required for background ingestion and admin logic |
ADMIN_EMAIL |
Yes | Comma-separated list of admin emails |
ENCRYPTION_KEY |
Yes | 32-byte hex string for AES-256-GCM |
UPSTASH_REDIS_REST_URL |
Yes | Upstash Redis connection URL |
UPSTASH_REDIS_REST_TOKEN |
Yes | Upstash Redis access token |
ENABLE_DIRECT_SCRAPE |
No | Set to true to enable direct platform scraping (Disabled in Cloud) |
- v1.1.0: Admin Auth Utilities & System Configuration Dashboard
- v1.0.2: Atomic Quotas & Google OAuth Integration
- v1.0.0: Production Security Finalization & Consent Gate
- v0.9.8: Multi-token Search & Search Hardening
- v0.9.6: Admin Dashboard & Interactive Demo Sandbox
- Multi-tenant shared inbound email domain (
@alerts.tuklas.dev) - Connector Marketplace (User-installable site parsers)
- Expo-based Mobile Client (iOS + Android)
- Billing & Subscription integration (Stripe)
Licensed under BUSL 1.1 — Free for personal use and self-hosting.