{"id":28438961,"url":"https://github.com/pitzzahh/lrnr","last_synced_at":"2026-04-05T08:33:25.911Z","repository":{"id":296985597,"uuid":"995243910","full_name":"pitzzahh/lrnr","owner":"pitzzahh","description":"A Learning Management System API built with Hono, Bun, and OpenAPI documentation. Fast, type-safe, and developer-friendly.","archived":false,"fork":false,"pushed_at":"2025-06-26T07:31:01.000Z","size":243,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-08T13:56:40.374Z","etag":null,"topics":["bun","hono","openapi","scalar","zod"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pitzzahh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-03T07:26:17.000Z","updated_at":"2025-07-15T03:29:09.000Z","dependencies_parsed_at":"2025-06-03T19:25:14.947Z","dependency_job_id":"162e0c52-282c-48e3-9065-24419d818809","html_url":"https://github.com/pitzzahh/lrnr","commit_stats":null,"previous_names":["pitzzahh/lrnr"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pitzzahh/lrnr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitzzahh%2Flrnr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitzzahh%2Flrnr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitzzahh%2Flrnr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitzzahh%2Flrnr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pitzzahh","download_url":"https://codeload.github.com/pitzzahh/lrnr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitzzahh%2Flrnr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31430009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T08:13:15.228Z","status":"ssl_error","status_checked_at":"2026-04-05T08:13:11.839Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","hono","openapi","scalar","zod"],"created_at":"2025-06-06T02:05:56.842Z","updated_at":"2026-04-05T08:33:25.877Z","avatar_url":"https://github.com/pitzzahh.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LRNR - Learning Management System API\n\nA REST API for a learning management system built with Hono, Bun, and PostgreSQL.\n\n## Features\n\n- RESTful API with OpenAPI 3.0 specification\n- Session-based authentication with HTTP-only cookies\n- Role-based access control (Admin, Teacher, Student)\n- User, course, category, and enrollment management\n- Request/response validation with Zod schemas\n- PostgreSQL database with Drizzle ORM\n- Interactive API documentation with Scalar\n- TypeScript for type safety\n- Code quality tools (Biome for linting and formatting)\n\n## Technology Stack\n\n- **Runtime**: Bun\n- **Framework**: Hono\n- **Database**: PostgreSQL with Drizzle ORM\n- **Authentication**: Session-based with HTTP-only cookies\n- **Authorization**: Role-based access control\n- **Validation**: Zod schemas\n- **Documentation**: OpenAPI 3.0 with Scalar UI\n- **Code Quality**: Biome (linting and formatting)\n- **Language**: TypeScript\n\n## Installation\n\n### Prerequisites\n\n- [Bun](https://bun.sh/) runtime\n- PostgreSQL database\n\n### Setup\n\n1. Clone the repository:\n```bash\ngit clone \u003crepository-url\u003e\ncd lrnr\n```\n\n2. Install dependencies:\n```bash\nbun install\n```\n\n3. Set up your environment variables:\n```bash\n# Create .env file with your configuration\nDATABASE_HOST=localhost\nDATABASE_PORT=5432\nDATABASE_USER=your_username\nDATABASE_PASSWORD=your_password\nDATABASE_NAME=lrnr\nSESSION_SECRET=your-session-secret\nPORT=3000\nNODE_ENV=development\n```\n\n4. Run database migrations:\n```bash\nbun run db:migrate\n```\n\n5. Start the development server:\n```bash\nbun run dev\n```\n\nThe API will be available at `http://localhost:3000` with interactive documentation at `http://localhost:3000/reference`.\n\n## Development\n\n### Available Scripts\n\n| Command | Description |\n|---------|-------------|\n| `bun run dev` | Start development server with hot reload |\n| `bun run lint` | Check code with Biome |\n| `bun run lint:fix` | Fix linting issues |\n| `bun run format` | Check code formatting |\n| `bun run format:fix` | Format code |\n| `bun run check` | Run code quality checks |\n| `bun run db:generate` | Generate database migrations |\n| `bun run db:migrate` | Apply database migrations |\n| `bun run db:push` | Push schema changes to database |\n| `bun run db:studio` | Open Drizzle Studio |\n\n### Environment Configuration\n\nThe application requires the following environment variables:\n\n```env\n# Server Configuration\nPORT=3000\nNODE_ENV=development\n\n# Database Configuration\nDATABASE_HOST=localhost\nDATABASE_PORT=5432\nDATABASE_USER=your_username\nDATABASE_PASSWORD=your_password\nDATABASE_NAME=lrnr\n\n# Authentication Configuration\nSESSION_SECRET=your-session-secret\n```\n\n### Project Structure\n\n```\nsrc/\n├── app.ts              # Application setup and route registration\n├── index.ts            # Server entry point\n├── env.ts              # Environment variable validation\n├── db/\n│   ├── index.ts        # Database connection setup\n│   ├── schema/         # Database schema definitions\n│   │   ├── users.ts    # User schema with roles\n│   │   ├── sessions.ts # Session management schema\n│   │   ├── courses.ts  # Course schema\n│   │   ├── categories.ts # Category schema\n│   │   ├── enrollments.ts # Enrollment schema\n│   │   └── enums/      # Database enums (roles, status)\n│   └── migrations/     # Database migration files\n├── hooks/\n│   ├── auth.ts         # Authentication middleware\n│   └── pino-logger.ts  # Request logging middleware\n├── lib/\n│   ├── create-app.ts   # Hono app factory\n│   ├── configure-openapi.ts  # OpenAPI configuration\n│   ├── constants.ts    # Application constants\n│   ├── types.ts        # TypeScript type definitions\n│   └── auth/           # Authentication utilities\n│       └── index.ts    # Session management and password hashing\n└── routes/\n    ├── index.route.ts  # Root API route\n    ├── auth/           # Authentication endpoints\n    ├── users/          # User management endpoints\n    ├── courses/        # Course management endpoints\n    ├── categories/     # Category management endpoints\n    ├── enrollments/    # Enrollment management endpoints\n    └── llms/           # LLM integration endpoints\n```\n\n## Authentication\n\nThe API supports two authentication methods:\n\n1. **Session-based authentication** - Uses HTTP-only cookies, ideal for web applications\n2. **API key authentication** - Uses Bearer tokens, ideal for programmatic access\n\nUsers have different roles that control access to various endpoints.\n\n### User Roles\n\n- **STUDENT**: Default role for new users\n- **TEACHER**: Can manage courses and view enrollments\n- **ADMIN**: Full access to all system resources\n\n### Authentication Endpoints\n\n| Endpoint | Method | Description |\n|----------|---------|-------------|\n| `POST /auth/signup` | POST | Register a new user account |\n| `POST /auth/signin` | POST | Sign in with email and password |\n| `POST /auth/logout` | POST | Sign out and invalidate session |\n\n### API Key Management\n\n| Endpoint | Method | Description |\n|----------|---------|-------------|\n| `GET /api-keys` | GET | List user's API keys |\n| `POST /api-keys` | POST | Create a new API key |\n| `GET /api-keys/{id}` | GET | Get specific API key details |\n| `PATCH /api-keys/{id}` | PATCH | Update API key (name, expiration) |\n| `DELETE /api-keys/{id}` | DELETE | Revoke an API key |\n\n### Protected Routes\n\nMost API endpoints require authentication. The following routes are public:\n- `GET /` - API root/health check\n- `POST /auth/signup` - User registration\n- `POST /auth/signin` - User authentication\n- `GET /doc` - OpenAPI specification\n- `GET /reference` - API documentation\n\n### Session Management\n\n- Sessions are valid for 15 days by default\n- Sessions are automatically refreshed on API usage  \n- HTTP-only cookies are used for security\n- Session data is stored in the database\n\n### API Key Management\n\n- API keys are prefixed with `lrnr_` for identification\n- Keys can have optional expiration dates\n- Keys are hashed before storage (never stored in plain text)\n- Last usage time is tracked for each key\n- Keys can be revoked/deactivated at any time\n\n### Usage Examples\n\n**Register a new user:**\n```bash\ncurl -X POST http://localhost:3000/auth/signup \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"John Doe\",\n    \"email\": \"john@example.com\", \n    \"password\": \"securepassword123\",\n    \"password_confirmation\": \"securepassword123\"\n  }'\n```\n\n**Sign in (session-based):**\n```bash\ncurl -X POST http://localhost:3000/auth/signin \\\n  -H \"Content-Type: application/json\" \\\n  -c cookies.txt \\\n  -d '{\n    \"email\": \"john@example.com\",\n    \"password\": \"securepassword123\"\n  }'\n```\n\n**Create an API key:**\n```bash\ncurl -X POST http://localhost:3000/api-keys \\\n  -H \"Content-Type: application/json\" \\\n  -b cookies.txt \\\n  -d '{\n    \"name\": \"My API Key\"\n  }'\n```\n\n**Use session authentication:**\n```bash\ncurl -X GET http://localhost:3000/users \\\n  -H \"Content-Type: application/json\" \\\n  -b cookies.txt\n```\n\n**Use API key authentication:**\n```bash\ncurl -X GET http://localhost:3000/users \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer lrnr_your_api_key_here\"\n```\n\n## Security\n\nThe application implements standard security practices:\n\n- Password hashing for user credentials\n- HTTP-only cookies to prevent XSS attacks\n- API key hashing (keys never stored in plain text)\n- Input validation using Zod schemas\n- Role-based access control for endpoints\n- Parameterized database queries\n- Environment variables for sensitive configuration\n\n## API Documentation\n\nInteractive API documentation is available at:\n- `/doc` - OpenAPI JSON specification\n- `/reference` - Scalar UI for testing endpoints\n\nThe documentation includes request/response schemas, authentication requirements, and example requests.\n\n## Troubleshooting\n\n### Common Issues\n\n**Database Connection Problems:**\n- Verify PostgreSQL is running\n- Check database credentials in environment variables\n- Ensure database exists and is accessible\n\n**Authentication Issues:**\n- Check that cookies are being sent with requests\n- Verify session hasn't expired\n- Ensure proper authentication headers\n\n### Development Notes\n\n- Use `bun run db:studio` to inspect database contents\n- Check server logs for detailed error information\n- Visit `/reference` for interactive API testing\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/new-feature`)\n3. Make your changes\n4. Run tests and linting (`bun run check`)\n5. Commit your changes (`git commit -m 'Add new feature'`)\n6. Push to the branch (`git push origin feature/new-feature`)\n7. Create a Pull Request\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpitzzahh%2Flrnr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpitzzahh%2Flrnr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpitzzahh%2Flrnr/lists"}