A trusted digital Coptology platform.

Publications · Grammar · Dictionary · Practice · Public APIs · Shenute AI

---

Coptic Compass brings together a searchable dictionary, structured grammar lessons, cross-pillar practice, publications, Shenute AI, public APIs, and private learning workspaces for Coptic language study and research.

Features

• Searchable Dictionary: 6,300+ normalized checked-in entries with Coptic, English, Dutch, and Greek-context lookup. Includes dialect forms, lexical relations, canonical entry pages, and a built-in virtual keyboard.
• Interactive Grammar Lessons: Reading and study modes with exercises, footnotes, and concept glossaries linked directly to dictionary sources.
• Practice: Spaced-repetition review for dictionary forms, grammar prompts, mixed daily study, and saved entries.
• Shenute AI Assistant: OCR-assisted image prompts backed by pgvector RAG, integrating THOTH AI, OpenRouter, Gemini, and Hugging Face.
• Public APIs: Read-only grammar and dictionary JSON endpoints plus OpenAPI documentation for developers and educators.
• Student & Instructor Workspaces: Private dashboards for progress tracking, exercise submissions, reviews, and notifications.
• Localized UI: Full support for both English and Dutch.

Interface

Quickstart

The application is built on Next.js 16 (App Router), React 19, Tailwind CSS 4, and Supabase.

git clone https://github.com/KyroHub/CopticCompass.git
cd CopticCompass
nvm use
npm install
npm run dev

Open http://localhost:3000 in your browser.

Note

To enable Supabase auth, AI routing, or email features locally, copy .env.example to .env.local and add your credentials. See our Architecture Docs for more details.

Repository Guide

This repo is organized around a few clear layers:

• src/app owns thin routes, route handlers, metadata, and app shell entry points.
• src/features owns feature-specific UI, hooks, server helpers, and logic.
• src/actions owns shared server actions used by forms and client mutations.
• src/lib owns shared infrastructure such as Supabase wiring, locale helpers, metadata, and validation.
• src/content/grammar owns typed grammar source files that are exported into checked-in data.
• public/data owns the generated or checked-in datasets consumed by the app and public API.
• supabase owns SQL migrations and Edge Functions.
• tests/e2e owns the Playwright smoke tests used in CI.

For structural changes, treat docs/architecture.md as the source of truth. Product logic should default to src/features/<feature>; src/lib is only for infrastructure that is genuinely shared across features. As feature surfaces grow, keep routes and page clients as orchestration shells and split reusable components, hooks, server pipelines, schemas, and validation rules by named responsibility.

Common Commands

The main scripts in package.json are:

• npm run dev - start the local app with the webpack dev server.
• npm run build - create a production build, including the grammar data export step.
• npm run lint - run ESLint with zero-warnings enforcement.
• npm run test - run the Vitest suite.
• npm run test:e2e - run Playwright end-to-end tests.
• npm run test:e2e:local - build first, then run the Playwright smoke tests.
• npm run knip - check for dead code and unused exports.
• npm run format:check - verify formatting with Prettier.
• npm run data:grammar:export - regenerate the public grammar JSON bundle from source.
• npm run db:migrations:list - compare local and linked Supabase migrations.
• npm run db:push:dry-run - preview pending Supabase migration changes.
• npm run db:push - apply pending Supabase migrations to the linked project.

Environment Setup

Start with .env.example and fill in only the services you need. The most common values are:

• Supabase URL and anon/service-role keys for auth and server-side data access.
• Resend API keys and sender addresses for contact and notification flows.
• Optional Upstash or Vercel KV settings for shared rate limiting.
• AI provider keys for Shenute AI and embedding workflows.
• OCR service settings for the server-side OCR proxy.

For production and external callbacks, the canonical site URL should be https://www.copticcompass.com.

Validation Before PRs

For CI parity from a clean checkout, run the same core checks locally:

npm ci
npm run format:check
npm run knip
npm run lint
npm run test
npm run build

If you change routing, auth, metadata, redirects, or major UI flows, also install the Playwright browser and run the smoke suite:

npx playwright install --with-deps chromium
npm run test:e2e

Documentation

For deep dives into the technical architecture, environment setup, API surfaces, or localization guidelines, start with the Docs Overview:

• Architecture & Workflows
• Coptic Compass Brand Book
• UI Guide
• Dictionary JSON Guide
• Environment & Deployment Setup
• API, AI, and Data Workflows
• AI & RAG Distillation Pipeline
• Dutch Localization Style Guide

Contributing

Contributions are welcome! Whether it's lexical corrections, UI refinements, or pedagogical improvements, we'd love your help.

Please read CONTRIBUTING.md and review our Code of Conduct before submitting a pull request.

License & Attribution

• Source code: MIT License
• Content & Data: Grammar lessons, dictionary data, and publication metadata are subject to specific academic rights. Please preserve scholarly attribution and source context when reusing material.
• THOTH AI Credits: Created by Dr. So Miyagawa (University of Tsukuba). Learn more.