{"id":28910880,"url":"https://github.com/sakan811/sakumari","last_synced_at":"2026-04-12T00:03:16.343Z","repository":{"id":249428345,"uuid":"831486966","full_name":"sakan811/SakuMari","owner":"sakan811","description":"Japanese Kana Flashcard Web App for practicing Japanese kana, e.g., Hiragana and Katakana","archived":false,"fork":false,"pushed_at":"2025-06-19T14:34:11.000Z","size":2084,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-19T14:45:25.003Z","etag":null,"topics":["flashcard","flashcards","hiragana","japanese","japanese-language","japanese-study","javascript","katakana","nextjs","postgres","postgresql","typescript","web","webapp","website"],"latest_commit_sha":null,"homepage":"https://saku-mari.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sakan811.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}},"created_at":"2024-07-20T17:37:10.000Z","updated_at":"2025-06-16T17:46:53.000Z","dependencies_parsed_at":"2024-12-07T13:30:36.150Z","dependency_job_id":"543cfffa-3410-46ca-8a8b-cc17f6a7fdc9","html_url":"https://github.com/sakan811/SakuMari","commit_stats":null,"previous_names":["sakan811/kana-flashcard-web-app","sakan811/sakumari"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/sakan811/SakuMari","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sakan811%2FSakuMari","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sakan811%2FSakuMari/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sakan811%2FSakuMari/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sakan811%2FSakuMari/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sakan811","download_url":"https://codeload.github.com/sakan811/SakuMari/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sakan811%2FSakuMari/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261174224,"owners_count":23120224,"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","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":["flashcard","flashcards","hiragana","japanese","japanese-language","japanese-study","javascript","katakana","nextjs","postgres","postgresql","typescript","web","webapp","website"],"created_at":"2025-06-21T18:32:24.649Z","updated_at":"2026-04-09T20:36:50.700Z","avatar_url":"https://github.com/sakan811.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SakuMari - Japanese Kana Flashcard App\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/SakuMari.png\" alt=\"SakuMari App Screenshot\" width=\"250\" /\u003e\n  \u003cbr\u003e\u003c/br\u003e\n\u003c/div\u003e\n\n[![Web-App Test](https://github.com/sakan811/SakuMari/actions/workflows/test-app.yml/badge.svg)](https://github.com/sakan811/SakuMari/actions/workflows/test-app.yml)\n[![E2E Test](https://github.com/sakan811/SakuMari/actions/workflows/playwright.yml/badge.svg)](https://github.com/sakan811/SakuMari/actions/workflows/playwright.yml)\n[![Docker CI](https://github.com/sakan811/SakuMari/actions/workflows/docker-ci.yml/badge.svg)](https://github.com/sakan811/SakuMari/actions/workflows/docker-ci.yml)\n\nA modern web application for learning Japanese Hiragana and Katakana characters through interactive flashcards with adaptive learning, comprehensive progress tracking, and AI-powered personalized learning tips.\n\n## Features\n\n🔐 **Secure Login** - Sign in with Google, practice safely\n\n🧠 **Smart Learning** - Algorithm focuses on characters you struggle with most\n\n⌨️ **Dual Modes** - Type answers or choose from multiple-choice options\n\n📊 **Progress Tracking** - See your improvement with detailed analytics\n\n🤖 **AI Tips** - Get personalized learning advice from Google Gemini\n\n📱 **Mobile Responsive** - Learn on any device with our responsive design\n\n_For detailed technical documentation, see [docs/features.md](docs/features.md)_\n\n## Architecture\n\n**Tech Stack:** Next.js 16 + PostgreSQL 17 + NextAuth.js v5 + Google Gemini AI\n\n**Key Components:** Adaptive FlashcardProvider → Practice/Dashboard Pages → API Layer → Database\n\n_For detailed architecture documentation, see [docs/architecture.md](docs/architecture.md)_\n\n## Package Manager\n\nThis project uses **pnpm** as its package manager. You'll need pnpm installed to run the development commands.\n\nVisit: \u003chttps://pnpm.io/installation\u003e\n\n## Google OAuth Setup\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com/)\n2. Create/select a project \u003e \"APIs \u0026 Services\" \u003e \"Credentials\"\n3. Create \"OAuth client ID\" (configure consent screen if prompted)\n4. Set authorized redirect URIs:\n   - Development: `http://localhost:3000/api/auth/callback/google`\n   - Production: `https://yourdomain.com/api/auth/callback/google`\n5. Copy Client ID and Secret to `.env` file\n\nMore details: \u003chttps://developers.google.com/identity/gsi/web/guides/get-google-api-clientid\u003e\n\n## Environment Setup\n\nCopy `.env.example` to `.env` and configure:\n\n```bash\n# Required - Generate at https://auth-secret-gen.vercel.app/\nAUTH_SECRET=your_random_secret_here\n\n# Database (localhost is default for local dev and E2E tests)\nPOSTGRES_DB=sakumari\nPOSTGRES_HOST=localhost\nPOSTGRES_USER=postgres\nPOSTGRES_PASSWORD=postgres\nPOSTGRES_PORT=5432\n\n# Database URLs\nPOSTGRES_PRISMA_URL=postgresql://postgres:postgres@localhost:5432/sakumari\nPOSTGRES_URL_NON_POOLING=postgresql://postgres:postgres@localhost:5432/sakumari\n\n# Google OAuth\nAUTH_GOOGLE_ID=your_google_client_id\nAUTH_GOOGLE_SECRET=your_google_client_secret\n\n# AI Learning Tips\nGEMINI_API_KEY=your_gemini_api_key_here\nMODEL_NAME=gemini-2.5-flash-lite\n\n# Local Redis for Rate Limiting\nREDIS_HOST=localhost\nREDIS_PORT=6379\nREDIS_PASSWORD=\nREDIS_DB=0\n\n# E2E test credentials only\nCREDS_PROVIDER=true\nCREDS_TEST_EMAIL=test@sakumari.local\nCREDS_TEST_PASSWORD=TestPassword123!\n```\n\n## Development Commands\n\n```bash\n# Development\npnpm run dev              # Start dev server\npnpm run build            # Build production app\npnpm run lint             # Run linter\npnpm run format           # Format code with Prettier\npnpm run test:all         # Run all tests and quality checks\n\n# License Management\npnpm run license:add      # Add license headers to all files\npnpm run license:remove   # Remove license headers from files\npnpm run license:check    # Check license header compliance\n```\n\n## Local Development Setup\n\n```bash\n# Clone and install\ngit clone https://github.com/sakan811/SakuMari.git\ncd SakuMari\npnpm install\n\n# Start database and Redis\npnpm run docker:db\n\n# Setup database (migrations + seed)\npnpm run db:setup\n\n# Start development server\npnpm run dev\n```\n\nVisit \u003chttp://localhost:3000\u003e\n\n## Docker Compose Setup\n\nFor isolated testing environment:\n\n### Prerequisites\n\n```bash\n# Install dependencies first (required for Prisma commands)\npnpm install\n```\n\n**Note**: Even though services run in containers, Prisma CLI commands execute on the host machine and require local dependencies.\n\n### Setup Steps\n\n```bash\n# Start full stack (Docker automatically configures database and Redis hosts)\npnpm run docker:dev-up\n\n# Setup database\npnpm run db:setup\n\n# Access services\n# App: http://localhost:3000\n\n# Docker Management\npnpm run docker:logs      # View all service logs\npnpm run docker:logs-app  # View app container logs only\npnpm run docker:status    # Check service status\npnpm run docker:down      # Stop all services\npnpm run docker:clean     # Remove all containers + volumes\n```\n\n**Note**: Docker Compose automatically overrides `POSTGRES_HOST=db` and `REDIS_HOST=redis` for containerized services. No manual `.env` editing required.\n\n## E2E Test Setup\n\n### Prerequisites\n\n```bash\n# Install dependencies first (required for Prisma commands and test runners)\npnpm install\n```\n\n**Note**: E2E tests use Prisma commands for database setup and Playwright for testing, both of which require local dependencies.\n\n### Environment Configuration\n\nDefault `.env` configuration works for E2E tests:\n\n```bash\n# Database (localhost is the default)\nPOSTGRES_HOST=localhost\nPOSTGRES_DB=sakumari\nPOSTGRES_USER=postgres\nPOSTGRES_PASSWORD=postgres\nPOSTGRES_PORT=5432\n\n# Required for E2E test authentication only\nCREDS_PROVIDER=true\nCREDS_TEST_EMAIL=test@sakumari.local\nCREDS_TEST_PASSWORD=TestPassword123!\n\n# Other required variables\nAUTH_SECRET=your_generated_secret_here\n```\n\n**Note**: No special database configuration needed - the default localhost setting works for both local development and E2E testing.\n\n**Test Commands**:\n\n```bash\n# Unit Tests\npnpm run test             # Unit tests (watch)\npnpm run test:run         # Unit tests once\npnpm run test:coverage    # Unit tests with coverage\n\n# Database Tests\npnpm run test:db          # Database tests (once)\npnpm run test:db:watch    # Database tests (watch)\npnpm run test:db:coverage # Database tests with coverage\npnpm run test:db:setup    # Setup database test environment\npnpm run test:db:full     # Database tests with fresh setup\npnpm run test:db:clean    # Clean database test artifacts\n\n# Integration Tests\npnpm run test:integration           # Integration tests (rate limiting)\npnpm run test:integration:coverage  # Integration tests with coverage\n\n# E2E Tests\npnpm run test:e2e:setup   # Setup E2E test environment\npnpm run test:e2e:build   # Build app for E2E testing\npnpm run test:e2e:full    # Full E2E test workflow\npnpm run test:e2e         # Run tests only (if already set up)\npnpm run test:e2e:clean   # Clean up test environment\n\n# All Tests\npnpm run test:all         # Run all tests and quality checks\n```\n\n## Test Document\n\nFor comprehensive test coverage and test case documentation, see [docs/test-cases.md](docs/test-cases.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsakan811%2Fsakumari","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsakan811%2Fsakumari","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsakan811%2Fsakumari/lists"}