foljapp

A working Albanian verb reference built around a reusable TypeScript morphology engine and a Rust corpus-evidence pipeline.

Search and browse	Full conjugation reference

Actual search-to-reference proof

This six-second capture comes from the public deployment. It shows the real search suggestions for pun, stable navigation to /verb/punoj, and the conjugation reference loading—not a staged mockup. The exact frame, browser, encoding, and privacy boundary is recorded in docs/motion/README.md.

Status

Pre-alpha. The web app, conjugation engine, verb corpus, reference pages, playground, and local corpus tooling are active. The current public build is at foljapp.pages.dev.

Product surface

• Search and browse the checked-in verb corpus.
• Open a citation-aware verb page with principal parts, full paradigms, IPA, English glosses, and decomposition traces.
• Explore forms in the playground, run practice sessions, and read the grammar articles and source register.
• Consume the same engine through the read-only verb index, verb-detail JSON, IGT, CoNLL-U, and OpenAPI document.

Layout

apps/web/              Next.js 15 app: UI, routes, and API handlers
packages/engine/       TypeScript Albanian morphology/conjugation engine
packages/data/         Checked-in verb data schemas and loaders
data/verbs/            Checked-in verb corpus
data/opus/             Small checked-in parallel-sentence fallback index
data/corpora/          Download ledger only; raw corpora stay in .cache/
scripts/               Narrow build/download utilities
tools/corpus-indexer/  Rust scanner for local corpus indexing
openspec/              Specs, changes, and roadmap

Local generated artifacts, downloaded corpora, SQLite indexes, and build caches belong under .cache/ and are intentionally not deployed.

App vs Corpus Lab

apps/, packages/, data/verbs/, and data/opus/examples.json are the website/runtime surface. They should stay small enough to build and deploy.

data/corpora/, scripts/*corpus*, and tools/corpus-indexer/ are the local corpus lab. They download, scan, audit, and explain large corpora from .cache/; their outputs are evidence for development and future backend services, not Cloudflare Pages assets.

Evidence flow

flowchart LR
  V["Checked-in verb JSON"] --> D["Data schemas and validation"]
  D --> E["TypeScript morphology engine"]
  E --> W["Next.js reference pages and read-only API"]
  E --> T["Generated search targets"]

  subgraph L["Local corpus lab — not deployed"]
    C["Raw corpora in .cache"] --> R["Rust corpus indexer"]
    T --> R
    R --> S["Retained examples, indexes, and audit reports"]
  end

  S -. "local evidence" .-> W

Loading

The deployment boundary is deliberate: the public app ships the reviewed verb data and deterministic engine, while raw corpora, local SQLite/Tantivy indexes, and large generated reports remain outside the Cloudflare Pages artifact.

Roadmap

The full roadmap and per-capability specs live in openspec/. See openspec/config.yaml for the project context and 14-capability roadmap across 5 phases.

Active changes:

openspec list

Local development

nvm use         # activates Node version pinned in .nvmrc
npm ci
npm run dev     # boots the webapp at http://localhost:3000

Local corpus indexing

The website can read local sentence examples from .cache/corpus-local-full.sqlite. That file is generated locally from raw corpora and is not committed.

npm run build:corpus-targets      # generated foljapp forms to search for
npm run scan:local-corpus         # Rust generated-form classifier over downloaded corpora
npm run build:local-corpus-index  # both steps above
npm run build:corpus-candidate-cache # optional parsed-candidate cache for reruns
npm run scan:local-corpus:cached  # classifier using the complete candidate cache
npm run build:corpus-search-index # Tantivy phrase-search index from retained examples
npm run search:corpus -- --query="të punoj"

See data/corpora/README.md for downloaded corpus inventory and source notes, and tools/corpus-indexer/README.md for the Rust scanner commands.

Quality gates

npm run typecheck   # TypeScript strict mode across all workspaces
npm run lint        # ESLint (Next.js + import-sort)
npm test            # Vitest across all workspaces
npm run verify:proof # README motion asset, link, and provenance contract
npm run build       # Next.js production build
npm run test:e2e    # Playwright E2E (requires browsers installed)
npm run audit:deps # npm audit at the high level, with one documented exception

GitHub Actions protects the morphology engine with TypeScript regression checks, verifies the shipped product flows in Chromium, builds the production app, audits dependencies, and enforces Rust formatting, Clippy, and corpus-index integrity—with read-only permissions and immutable action revisions.

Security and maintenance

Report vulnerabilities through GitHub's private reporting form and review the security policy for the deployed-app and local-corpus boundary. Dependabot monitors the npm workspace, Rust corpus indexer, and GitHub Actions; security fixes are grouped separately from routine minor and patch maintenance.

License

Original source code and documentation in this repository are available under the MIT License. Third-party dependencies and cited linguistic sources remain subject to their own terms and attribution requirements.