{"id":42009192,"url":"https://github.com/vichannnnn/holy-grail","last_synced_at":"2026-01-26T02:18:12.696Z","repository":{"id":178350725,"uuid":"644833280","full_name":"vichannnnn/holy-grail","owner":"vichannnnn","description":"Holy Grail is an online open-content collaborative depository web application for students in Singapore to share notes and resources for educative purpose. ","archived":false,"fork":false,"pushed_at":"2026-01-23T08:11:58.000Z","size":32215,"stargazers_count":28,"open_issues_count":1,"forks_count":4,"subscribers_count":1,"default_branch":"staging","last_synced_at":"2026-01-23T16:47:05.231Z","etag":null,"topics":["fastapi","python3"],"latest_commit_sha":null,"homepage":"https://grail.moe","language":"Python","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/vichannnnn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2023-05-24T10:58:07.000Z","updated_at":"2026-01-22T23:31:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"5d0a31c1-141b-4277-acd2-a868be7c1416","html_url":"https://github.com/vichannnnn/holy-grail","commit_stats":null,"previous_names":["vichannnnn/holy-grail"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/vichannnnn/holy-grail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vichannnnn%2Fholy-grail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vichannnnn%2Fholy-grail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vichannnnn%2Fholy-grail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vichannnnn%2Fholy-grail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vichannnnn","download_url":"https://codeload.github.com/vichannnnn/holy-grail/tar.gz/refs/heads/staging","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vichannnnn%2Fholy-grail/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28764871,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T00:37:26.264Z","status":"online","status_checked_at":"2026-01-26T02:00:08.215Z","response_time":59,"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":["fastapi","python3"],"created_at":"2026-01-26T02:18:12.054Z","updated_at":"2026-01-26T02:18:12.690Z","avatar_url":"https://github.com/vichannnnn.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Holy Grail\n\n[![codecov](https://codecov.io/gh/vichannnnn/holy-grail/branch/dev/graph/badge.svg)](https://codecov.io/gh/vichannnnn/holy-grail/tree/dev)\n[![Python](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/)\n[![Docker](https://img.shields.io/badge/built%20with-Docker-blue)](https://www.docker.com/)\n[![Build and Deploy](https://github.com/vichannnnn/holy-grail/actions/workflows/build-and-deploy.yml/badge.svg?branch=master)](https://github.com/vichannnnn/holy-grail/actions/workflows/build-and-deploy.yml)\n[![Pull Request Tests](https://github.com/vichannnnn/holy-grail/actions/workflows/pull-request-test.yml/badge.svg)](https://github.com/vichannnnn/holy-grail/actions/workflows/pull-request-test.yml)\n\n![Grail-chan](https://image.himaa.me/grail-chan-sparkling-640x480.png)\n\nHoly Grail is a completely free-to-access web library aimed at Singaporean students that houses all the summary\nnotes and practice papers for GCE 'O' Levels, GCE 'A' Levels and International Baccalaureate.\n\n## Overview\n\nHoly Grail is a modern full-stack web application built with:\n- **Backend**: FastAPI (Python 3.11) with PostgreSQL database\n- **Frontend**: Next.js 15/16 (React 19) with TypeScript and Tailwind CSS\n- **Task Queue**: Celery with Redis broker for async processing\n- **Infrastructure**: Turborepo monorepo with Docker containerization\n\n## Quick Start\n\n### Prerequisites\n- Node.js 18+ and [Bun](https://bun.sh/) 1.2.22+\n- Python 3.11+ with [UV](https://docs.astral.sh/uv/) package manager\n- Docker\n\n### Setup (3 Simple Steps)\n\n1. **Clone and install dependencies**\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd holy-grail\n   bun install\n   ```\n\n2. **Start the database**\n   ```bash\n   bun run db\n   ```\n\n3. **Start the development servers**\n   ```bash\n   bun run dev\n   ```\n\nThat's it! You can now access:\n- **Backend API**: http://localhost:8000/docs\n- **Frontend**: http://localhost:3000 (grail.moe)\n\nOr use `bun run dev:full` to start everything with database, migrations, and seed data in one command.\n\n## Architecture\n\n```\n┌──────────────────┐\n│     Frontend     │\n│   (grail.moe)    │\n│   Port: 3000     │\n└────────┬─────────┘\n         │\n   ┌─────▼─────┐\n   │  Backend  │\n   │ (FastAPI) │\n   │ Port:8000 │\n   └─────┬─────┘\n         │\n   ┌─────┼─────────────────────┐\n   │     │             │       │\n┌──▼───┐ ┌▼────┐ ┌─────▼─────┐ ┌▼──────────┐\n│Postgr│ │Redis│ │  Celery   │ │OpenSearch │\n│eSSQL │ │     │ │  (Tasks)  │ │ (Search)  │\n│:5432 │ │:6379│ │ Port:8001 │ │  :9200    │\n└──────┘ └─────┘ └───────────┘ └───────────┘\n```\n\n- **Frontend** (`/apps/frontend`): The educational platform serving free notes and papers\n- **Backend** (`/apps/backend`): FastAPI server handling API requests\n- **Task Worker** (`/apps/task`): Celery worker for async jobs (emails, analytics)\n\n## Project Structure\n\n```\nholy-grail/\n├── apps/\n│   ├── backend/        # FastAPI backend application\n│   ├── frontend/       # Educational platform (Next.js)\n│   └── task/           # Celery task worker + API\n├── packages/\n│   ├── ui/             # Shared React component library\n│   └── tooling/        # Shared Biome and TypeScript configs\n├── docker/             # Docker configurations (PostgreSQL, Redis)\n├── docs/               # Project documentation\n├── claude/             # Claude Code organization\n│   ├── agents/         # Custom AI agents\n│   ├── docs/           # Development documentation\n│   ├── plans/          # Implementation plans\n│   └── tickets/        # Task tickets\n└── turbo.json          # Monorepo configuration\n```\n\n## Available Commands\n\nFrom the root directory:\n\n```bash\n# Quick Start\nbun install             # Install all dependencies\nbun run setup           # Initial Turborepo setup\nbun run dev:full        # Start DB, run migrations, seed data, and start all dev servers\n\n# Development\nbun run dev             # Start all dev servers (backend, frontend)\nbun run db              # Start PostgreSQL and Redis in Docker\nbun run migrate         # Run database migrations\nbun run seed            # Seed database with sample data\nbun run task            # Start Celery task worker\n\n# Code Quality\nbun run build           # Build all packages\nbun run test            # Run all tests\nbun run lint            # Lint all packages\nbun run format          # Format all code\n```\n\nFor package-specific commands, see the README in each package directory.\n\n## Technology Stack\n\n| Layer | Technology |\n|-------|-----------|\n| **Frontend** | React 19, Next.js 16, TypeScript, Tailwind CSS v4 |\n| **Backend** | FastAPI, Python 3.11, SQLAlchemy 2.0, Pydantic 2.0 |\n| **Database** | PostgreSQL 14.1, Alembic migrations |\n| **Search** | OpenSearch (full-text search) |\n| **Task Queue** | Celery 5.4, Redis 7.0.7 |\n| **Auth** | JWT-based with bcrypt password hashing |\n| **Storage** | AWS S3 for file storage |\n| **Analytics** | Google Analytics 4 |\n| **Infrastructure** | AWS ECS Fargate, Terraform Cloud |\n| **Package Managers** | Bun (Node), UV (Python) |\n| **Code Quality** | Ruff (Python), Biome (JS/TS), MyPy |\n\n## Documentation\n\n- [Setup Guide](./docs/SETUP.md) - Detailed setup instructions\n- [Development Guide](./docs/DEVELOPMENT.md) - Development workflow and tips\n- [Architecture](./docs/ARCHITECTURE.md) - System design and structure\n- [Troubleshooting](./docs/TROUBLESHOOTING.md) - Common issues and solutions\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n\nPlease make sure that all backend contributions are updated with appropriate tests and passed with `bun run test` first.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvichannnnn%2Fholy-grail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvichannnnn%2Fholy-grail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvichannnnn%2Fholy-grail/lists"}