| --- |
| title: Pram API |
| emoji: 🚀 |
| colorFrom: green |
| colorTo: blue |
| sdk: docker |
| app_port: 3000 |
| --- |
| <p align="center"> |
| <img src="./apps/web/public/logo.png" alt="Pram" width="200" /> |
| </p> |
|
|
| <h1 align="center">Pram</h1> |
|
|
| <p align="center"> |
| <strong>AI-powered multi-language test practice platform</strong><br /> |
| Generate authentic exam questions, run mock tests, and track your progress — all in one place. |
| </p> |
|
|
| <p align="center"> |
| <a href="#getting-started">Getting Started</a> · |
| <a href="#features">Features</a> · |
| <a href="#supported-exams">Exams</a> · |
| <a href="#project-structure">Structure</a> · |
| <a href="#support">Support</a> · |
| <a href="#license">License</a> |
| </p> |
|
|
| --- |
|
|
| ## What is Pram? |
|
|
| **Pram** is an open-source platform for practicing CPNS (Seleksi Calon Pegawai Negeri Sipil) exams. Users can generate questions for TWK, TIU, and TKP with AI, save them into question packages, take timed mock tests, and review results with detailed explanations in **Bahasa Indonesia**. |
|
|
| The project is a **Turborepo monorepo** managed with **Bun**. The web app talks to a **Hono + tRPC** backend backed by **PostgreSQL**, **Redis** (job queue), and **Better Auth**. |
|
|
| ## Features |
|
|
| - **AI question generation** — Quick mode (single-pass) and Agentic mode (multi-step pipeline) |
| - **CPNS Focus** — TWK, TIU, and TKP sections |
| - **20+ question formats** — Multiple choice, true/false, fill-in-blank, and more |
| - **Question bank & packages** — Organize generated questions into shareable or private packages |
| - **Mock tests & attempts** — Timed practice sessions with scoring and review |
| - **Analytics & leaderboard** — Track performance over time |
| - **User-managed AI keys** — Bring your own OpenAI-compatible API key |
| - **PWA** — Installable progressive web app |
|
|
| ## Supported Exam Sections |
|
|
| | Section | Type | Notes | |
| |---------|------|-------| |
| | TWK | Tes Wawasan Kebangsaan | Nasionalisme, Integritas, Bela Negara, Pilar Negara, Bahasa Indonesia | |
| | TIU | Tes Intelegensia Umum | Verbal, Numerik, Figural | |
| | TKP | Tes Karakteristik Pribadi | Pelayanan Publik, Jejaring Kerja, Sosial Budaya, TIK, Profesionalisme, Anti Radikalisme | |
|
|
| ## Tech Stack |
|
|
| | Layer | Technology | |
| |-------|------------| |
| | Runtime & package manager | [Bun](https://bun.sh) 1.3+ | |
| | Frontend | React 19, Vite, [TanStack Router](https://tanstack.com/router) | |
| | Backend | [Hono](https://hono.dev), [tRPC](https://trpc.io) | |
| | Database | PostgreSQL + [Drizzle ORM](https://orm.drizzle.team) | |
| | Queue | Redis + BullMQ (AI generation jobs) | |
| | Auth | [Better Auth](https://www.better-auth.com) (email/password) | |
| | UI | [shadcn/ui](https://ui.shadcn.com) in `packages/ui` | |
| | AI | OpenAI-compatible API (`packages/ai`) | |
| | Build | Turborepo + tsdown | |
|
|
| ## Prerequisites |
|
|
| - **[Bun](https://bun.sh)** `1.3.11` or later (see `packageManager` in root `package.json`) |
| - **PostgreSQL** 15+ |
| - **Redis** 7+ (required for background AI generation jobs) |
| - **SMTP server** (required for email verification and password reset) |
|
|
| > Use `bun` for all install and script commands. Do not use `pnpm`, `npm`, or `yarn` unless a global tool explicitly requires it. |
|
|
| ## Getting Started |
|
|
| ### 1. Clone and install |
|
|
| ```bash |
| git clone https://github.com/<your-org>/pram.git |
| cd pram |
| bun install |
| ``` |
|
|
| ### 2. Start PostgreSQL and Redis |
|
|
| The repo includes a Docker Compose file for local development: |
|
|
| ```bash |
| bun run db:start |
| ``` |
|
|
| This starts PostgreSQL on port `5432` and Redis on port `6379`. See [`packages/db/docker-compose.yml`](./packages/db/docker-compose.yml) for defaults. |
|
|
| Alternatively, point `DATABASE_URL` and `REDIS_URL` at your own instances. |
|
|
| ### 3. Configure environment |
|
|
| Copy the example env files: |
|
|
| ```bash |
| cp apps/server/.env.example apps/server/.env |
| cp apps/web/.env.example apps/web/.env |
| ``` |
|
|
| Edit **`apps/server/.env`**: |
|
|
| ```env |
| # PostgreSQL (matches docker-compose defaults) |
| DATABASE_URL=postgresql://postgres:password@localhost:5432/pram |
| |
| # Redis (defaults to redis://localhost:6379 if omitted) |
| REDIS_URL=redis://localhost:6379 |
| |
| # Auth — generate random strings ≥ 32 characters |
| BETTER_AUTH_SECRET=your-random-secret-at-least-32-chars |
| BETTER_AUTH_URL=http://localhost:3000 |
| CORS_ORIGIN=http://localhost:3001 |
| |
| # Encrypts user AI API keys at rest — ≥ 32 characters |
| API_KEY_ENCRYPTION_KEY=your-encryption-key-at-least-32-chars |
| |
| # SMTP (required for sign-up verification & password reset) |
| SMTP_HOST=smtp.example.com |
| SMTP_PORT=587 |
| SMTP_USER=your-smtp-user |
| SMTP_PASS=your-smtp-password |
| SMTP_FROM=noreply@example.com |
| |
| # Optional: platform-wide AI fallback (users normally set keys in Settings UI) |
| # PLATFORM_AI_API_KEY= |
| # PLATFORM_AI_BASE_URL= |
| # PLATFORM_AI_MODEL= |
| ``` |
|
|
| Edit **`apps/web/.env`**: |
|
|
| ```env |
| VITE_SERVER_URL=http://localhost:3000 |
| ``` |
|
|
| ### 4. Push database schema |
|
|
| ```bash |
| bun run db:push |
| ``` |
|
|
| Optionally seed reference data (exam types, sections): |
|
|
| ```bash |
| bun run db:seed |
| ``` |
|
|
| ### 5. Run the dev servers |
|
|
| ```bash |
| bun run dev |
| ``` |
|
|
| | Service | URL | |
| |---------|-----| |
| | Web app | [http://localhost:3001](http://localhost:3001) | |
| | API server | [http://localhost:3000](http://localhost:3000) | |
|
|
| Sign up, verify your email, then open **Settings** to add your OpenAI-compatible API key before generating questions. |
|
|
| ## AI Configuration |
|
|
| AI provider keys are **not** stored in server `.env` by default. Each user configures their own key in the **Settings** page. The server encrypts keys with `API_KEY_ENCRYPTION_KEY`. |
|
|
| Generation supports any **OpenAI-compatible** endpoint (OpenAI, OpenRouter, local LM Studio, etc.). |
|
|
| Two generation modes are available: |
|
|
| | Mode | Description | |
| |------|-------------| |
| | **Quick** | Single LLM call with schema validation and repair | |
| | **Agentic** | Multi-step pipeline: plan → shared passage → parallel question shards → validation | |
|
|
| AI logic lives in [`packages/ai/`](./packages/ai/). |
|
|
| ## Project Structure |
|
|
| ``` |
| pram/ |
| ├── apps/ |
| │ ├── web/ # Frontend (React + TanStack Router) — port 3001 |
| │ └── server/ # Backend entry (Hono + tRPC) — port 3000 |
| ├── packages/ |
| │ ├── ai/ # Prompts, schemas, quick & agentic pipelines |
| │ ├── api/ # tRPC routers, queue workers, business logic |
| │ ├── auth/ # Better Auth configuration |
| │ ├── config/ # Shared TypeScript configs |
| │ ├── db/ # Drizzle schema, migrations, docker-compose |
| │ ├── env/ # Environment validation (Zod) |
| │ └── ui/ # Shared shadcn/ui components & design tokens |
| ├── AGENTS.md # Contributor guide for AI agents & developers |
| └── turbo.json |
| ``` |
|
|
| Internal imports use the `@pram/*` workspace namespace. Apps should not import from each other directly — share code through `packages/*`. |
|
|
| ## Available Scripts |
|
|
| Run from the **repository root**: |
|
|
| | Command | Description | |
| |---------|-------------| |
| | `bun run dev` | Start web + server in development | |
| | `bun run dev:web` | Start web app only | |
| | `bun run dev:server` | Start server only | |
| | `bun run build` | Build all packages | |
| | `bun run check-types` | TypeScript check across the monorepo | |
| | `bun test` | Run all tests via Turborepo | |
| | `bun run db:push` | Push Drizzle schema to PostgreSQL | |
| | `bun run db:generate` | Generate migration files | |
| | `bun run db:migrate` | Run migrations | |
| | `bun run db:seed` | Seed reference data (exam types, sections) | |
| | `bun run db:studio` | Open Drizzle Studio | |
| | `bun run db:start` | Start PostgreSQL + Redis (Docker Compose) | |
| | `bun run db:stop` | Stop Docker Compose services | |
|
|
| ## Deployment |
|
|
| Production deploys use **two Coolify applications** from this repo (web + API server), plus **PostgreSQL** and **Redis**. The server does not serve the frontend build; the web app calls the API via `VITE_SERVER_URL`. |
|
|
| See **[`deploy/COOLIFY.md`](./deploy/COOLIFY.md)** for step-by-step Coolify setup, environment variables, Nixpacks configs (`deploy/server.nixpacks.toml`, `deploy/web.nixpacks.toml`), and a first-deploy checklist. |
|
|
| ## Development |
|
|
| ### Type checking |
|
|
| ```bash |
| bun run check-types |
| ``` |
|
|
| ### Testing |
|
|
| ```bash |
| bun test |
| ``` |
|
|
| Tests use **Bun's built-in test runner**. Unit tests live in `src/__tests__/` within each package. Integration tests in `packages/api` use PGlite (in-memory PostgreSQL). |
|
|
| ### Adding shadcn/ui components |
|
|
| From the project root: |
|
|
| ```bash |
| npx shadcn@latest add accordion dialog -c packages/ui |
| ``` |
|
|
| Import shared components: |
|
|
| ```tsx |
| import { Button } from "@pram/ui/components/button"; |
| ``` |
|
|
| Design tokens and global styles: [`packages/ui/src/styles/globals.css`](./packages/ui/src/styles/globals.css). |
|
|
| ### PWA assets |
|
|
| ```bash |
| cd apps/web && bun run generate-pwa-assets |
| ``` |
|
|
| ## Contributing |
|
|
| Contributions are welcome! Before opening a PR: |
|
|
| 1. Read [`AGENTS.md`](./AGENTS.md) for architecture, conventions, and common pitfalls. |
| 2. Run `bun run check-types` and `bun test`. |
| 3. Keep changes focused and match existing code style. |
|
|
| For AI-related changes, see the **AI Generation Context** section in `AGENTS.md` — adding a new question format touches schemas, prompts, attempt normalization, and frontend constants. |
|
|
|
|
| ## License |
|
|
| This project is licensed under the **[GNU Affero General Public License v3.0 (AGPL-3.0)](./LICENSE)**. |
|
|
| If you run a modified version as a network service, you must make the corresponding source code available to users of that service. |
|
|
| --- |
|
|
| <p align="center"> |
| Built with Bun, React, Hono, and tRPC. |
| </p> |
|
|
|
|
