{"id":30692882,"url":"https://github.com/deltacs99/navyblue-api","last_synced_at":"2025-09-02T05:06:05.580Z","repository":{"id":312678750,"uuid":"1048276495","full_name":"deltaCS99/navyblue-api","owner":"deltaCS99","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-01T09:05:43.000Z","size":122,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-01T11:42:04.229Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/deltaCS99.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-09-01T07:44:16.000Z","updated_at":"2025-09-01T09:05:46.000Z","dependencies_parsed_at":"2025-09-01T11:42:08.478Z","dependency_job_id":"8fb03b47-996d-4de1-a093-d8192a264a56","html_url":"https://github.com/deltaCS99/navyblue-api","commit_stats":null,"previous_names":["deltacs99/navyblue-api"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/deltaCS99/navyblue-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deltaCS99%2Fnavyblue-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deltaCS99%2Fnavyblue-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deltaCS99%2Fnavyblue-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deltaCS99%2Fnavyblue-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deltaCS99","download_url":"https://codeload.github.com/deltaCS99/navyblue-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deltaCS99%2Fnavyblue-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273233235,"owners_count":25068731,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-09-02T05:06:01.118Z","updated_at":"2025-09-02T05:06:05.567Z","avatar_url":"https://github.com/deltaCS99.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NavyBlue API - SA Exam Prep Platform\n\nA comprehensive RESTful API for South African exam preparation, built with [Node.js](https://nodejs.org), [TypeScript](https://www.typescriptlang.org), [Express](https://expressjs.com), and [Prisma](https://www.prisma.io).\n\nNavyBlue provides a self-marking exam preparation system where students can practice past papers and mark individual solution steps, enabling immediate feedback and personalized learning paths.\n\n## Key Features\n\n- **Self-Marking System**: Students mark individual solution steps for granular feedback\n- **Curriculum-Aligned Content**: Supports CAPS and IEB syllabi for Mathematics and Physical Sciences\n- **Topic-Based Progress**: Track performance across mathematical topics and subtopics\n- **Offline-First Ready**: API designed for Flutter Brick offline synchronization\n- **Admin Content Management**: Upload and manage exam papers, questions, and solution steps\n\n## Quick Start\n\nClone the repository:\n\n```bash\ngit clone \u003cyour-repo-url\u003e navyblue-api\ncd navyblue-api\n```\n\nInstall dependencies:\n\n```bash\npnpm install\n```\n\nSet up environment variables:\n\n```bash\ncp .env.example .env\n# Edit .env with your database credentials and JWT secrets\n```\n\nStart PostgreSQL database:\n\n```bash\ndocker run --name navyblue-postgres \\\n  -e POSTGRES_DB=navyblue_dev \\\n  -e POSTGRES_USER=navyblue \\\n  -e POSTGRES_PASSWORD=navyblue123 \\\n  -p 5432:5432 -d postgres:15-alpine\n```\n\nInitialize database:\n\n```bash\npnpm db:push\npnpm db:seed # Optional: Load sample curriculum data\n```\n\nStart development server:\n\n```bash\npnpm dev\n```\n\n## Table of Contents\n\n- [Features](#features)\n- [Commands](#commands)\n- [Environment Variables](#environment-variables)\n- [Project Structure](#project-structure)\n- [API Documentation](#api-documentation)\n- [Authentication](#authentication)\n- [Self-Marking System](#self-marking-system)\n- [Future Roadmap](#future-roadmap)\n- [Error Handling](#error-handling)\n- [Deployment](#deployment)\n\n## Features\n\n- **SQL Database**: [PostgreSQL](https://www.postgresql.org) with [Prisma](https://www.prisma.io) ORM\n- **Authentication \u0026 Authorization**: JWT tokens with refresh token rotation\n- **Self-Marking Engine**: Granular step-by-step solution marking system\n- **Content Management**: Admin tools for uploading papers and managing users\n- **Topic Progress Tracking**: Performance analytics by mathematical topics\n- **Validation**: Request data validation using [Joi](https://joi.dev)\n- **Logging**: Comprehensive logging with [Winston](https://github.com/winstonjs/winston)\n- **API Documentation**: Auto-generated with [Swagger](https://swagger.io/)\n- **Error Handling**: Centralized error handling with proper HTTP status codes\n- **Security**: HTTP headers, XSS protection, and rate limiting\n- **Testing**: Unit and integration tests with [Jest](https://jestjs.io)\n- **Docker Support**: Containerized deployment ready\n- **Process Management**: Production deployment with [PM2](https://pm2.keymetrics.io)\n\n## Commands\n\nDevelopment:\n\n```bash\npnpm dev          # Start development server with hot reload\npnpm build        # Build TypeScript to JavaScript\npnpm start        # Start production server\n```\n\nDatabase:\n\n```bash\npnpm db:push      # Push schema changes to database\npnpm db:studio    # Open Prisma Studio database browser\npnpm db:seed      # Seed database with sample data\npnpm db:reset     # Reset database (destructive)\n```\n\nTesting:\n\n```bash\npnpm test         # Run all tests\npnpm test:watch   # Run tests in watch mode\npnpm coverage     # Generate test coverage report\n```\n\nDocker:\n\n```bash\npnpm docker:dev        # Run development container\npnpm docker:prod       # Run production container\npnpm docker:dev-db:start  # Start PostgreSQL container\npnpm docker:dev-db:stop   # Stop PostgreSQL container\n```\n\nCode Quality:\n\n```bash\npnpm lint         # Run ESLint\npnpm lint:fix     # Fix ESLint errors\npnpm prettier     # Check Prettier formatting\npnpm prettier:fix # Fix Prettier formatting\n```\n\n## Environment Variables\n\n```bash\n# Server Configuration\nPORT=8080\nNODE_ENV=development\n\n# Database\nDATABASE_URL=postgresql://navyblue:navyblue123@localhost:5432/navyblue_dev\n\n# JWT Authentication\nJWT_SECRET=your-super-secret-jwt-key\nJWT_ACCESS_EXPIRATION_MINUTES=1440\nJWT_REFRESH_EXPIRATION_DAYS=30\n\n# File Upload\nMAX_FILE_SIZE=10MB\nUPLOAD_PATH=./uploads\n\n# Email (Optional)\nSMTP_HOST=smtp.gmail.com\nSMTP_PORT=587\nSMTP_USERNAME=your-email@gmail.com\nSMTP_PASSWORD=your-app-password\nEMAIL_FROM=noreply@navyblue.co.za\n\n# Admin Configuration\nADMIN_EMAIL=admin@navyblue.co.za\nADMIN_PASSWORD=change-in-production\n```\n\n## Project Structure\n\n```\nsrc/\n |--config/         # Configuration files and environment variables\n |--controllers/    # Request handlers and response logic\n |--docs/           # Swagger API documentation\n |--middlewares/    # Express middlewares (auth, validation, etc.)\n |--routes/         # API route definitions\n |--services/       # Business logic layer\n |--utils/          # Utility functions and helpers\n |--validations/    # Request validation schemas\n |--types/          # TypeScript type definitions\n |--app.ts          # Express application setup\n |--server.ts       # Server entry point\nprisma/\n |--schema.prisma   # Database schema definition\n |--migrations/     # Database migration files\n |--seed.ts         # Database seeding script\n```\n\n## API Documentation\n\nView the interactive API documentation at `http://localhost:8080/v1/docs` when running the server.\n\n### Core API Endpoints\n\n**Authentication:**\n```\nPOST /v1/auth/register     # Student registration\nPOST /v1/auth/login        # User login\nPOST /v1/auth/refresh      # Refresh access token\nGET  /v1/auth/me           # Get current user\n```\n\n**Papers \u0026 Questions:**\n```\nGET  /v1/papers                    # List exam papers (filtered)\nGET  /v1/papers/:id                # Get specific paper with questions\nGET  /v1/questions/:id             # Get question with parts/solutions\n```\n\n**Self-Marking System:**\n```\nPOST /v1/attempts                  # Start new attempt\nPOST /v1/attempts/:id/mark-step    # Mark individual solution step\nGET  /v1/attempts/:id/progress     # Get attempt progress\nPUT  /v1/attempts/:id/complete     # Complete attempt\n```\n\n**Progress \u0026 Analytics:**\n```\nGET  /v1/users/progress           # User progress by topics\nGET  /v1/users/weak-topics        # Areas needing improvement\n```\n\n**Admin Operations:**\n```\nPOST /v1/admin/papers             # Upload exam papers\nPOST /v1/admin/images             # Upload question images\nGET  /v1/admin/users              # Manage user accounts\n```\n\n## Authentication\n\nNavyBlue uses JWT tokens with refresh token rotation for secure authentication.\n\n### Student Registration\n```typescript\nPOST /v1/auth/register\n{\n  \"email\": \"student@school.co.za\",\n  \"password\": \"securePassword123\",\n  \"firstName\": \"John\",\n  \"lastName\": \"Doe\",\n  \"grade\": \"GRADE_12\",\n  \"province\": \"GAUTENG\",\n  \"syllabus\": \"CAPS\"\n}\n```\n\n### Admin Access\nAdmin users have additional permissions for content management and user administration. Admin status is assigned during user creation.\n\n## Self-Marking System\n\nThe core innovation of NavyBlue is the granular self-marking system where students evaluate individual solution steps.\n\n### How It Works\n\n1. **Start Attempt**: Student begins working on a paper\n2. **View Solutions**: Step-by-step worked solutions are provided\n3. **Mark Steps**: Student marks each step as Correct/Incorrect/Not Attempted\n4. **Calculate Progress**: Real-time scoring based on marked steps\n5. **Track Analytics**: Performance data feeds into progress tracking\n\n### Example Step Marking\n```typescript\nPOST /v1/attempts/{attemptId}/mark-step\n{\n  \"stepId\": \"step-uuid-123\",\n  \"status\": \"CORRECT\"\n}\n```\n\n## Future Roadmap\n\n### Planned Features\n- **Practice Paper Generation**: Template-based papers matching official CAPS/IEB structures\n- **AI-Powered Recommendations**: Personalized study plans based on performance analytics\n- **Advanced Progress Analytics**: Detailed insights and readiness assessments\n- **Multi-Subject Expansion**: Chemistry, Biology, and other STEM subjects\n- **Collaborative Learning**: Study groups and peer comparison features\n- **Mobile Optimization**: Enhanced Flutter app with full offline capabilities\n\n### Long-term Vision\n- **Institutional Dashboards**: School-wide analytics for educators\n- **Adaptive Learning Paths**: Dynamic content adjustment based on learning patterns\n- **Integration Ecosystem**: Seamless connection with existing educational platforms\n\n## Error Handling\n\nCentralized error handling provides consistent error responses:\n\n```json\n{\n  \"code\": 400,\n  \"message\": \"Invalid request data\",\n  \"stack\": \"Error stack (development only)\"\n}\n```\n\nCustom ApiError class for throwing specific errors:\n```typescript\nimport { ApiError } from '../utils/ApiError';\nimport httpStatus from 'http-status';\n\nthrow new ApiError(httpStatus.NOT_FOUND, 'Paper not found');\n```\n\n## Validation\n\nRequest validation using Joi schemas ensures data integrity:\n\n```typescript\nconst markStepSchema = {\n  body: Joi.object().keys({\n    stepId: Joi.string().required(),\n    status: Joi.string().valid('CORRECT', 'INCORRECT', 'NOT_ATTEMPTED').required()\n  })\n};\n```\n\n## Deployment\n\n### Development\n```bash\npnpm dev\n```\n\n### Production with PM2\n```bash\npnpm build\npm2 start ecosystem.config.js\n```\n\n### Docker\n```bash\ndocker build -t navyblue-api .\ndocker run -p 8080:8080 --env-file .env navyblue-api\n```\n\n### Environment Setup\n1. Set up PostgreSQL database\n2. Configure environment variables\n3. Run database migrations\n4. Seed initial data (sample papers, admin users)\n5. Configure file storage for images\n6. Set up monitoring and logging\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n**NavyBlue** - Empowering South African students with intelligent exam preparation and self-assessment tools.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeltacs99%2Fnavyblue-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeltacs99%2Fnavyblue-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeltacs99%2Fnavyblue-api/lists"}