Konsensus / Hukukça

This repository builds hukukca.org: Hukukça, an index of Turkish legal opinion where every entry can be traced to its source. For contested court decisions and similar yes/no legal questions, it records who holds which position, from two kinds of records:

• public statements by named lawyers, bar associations, and institutions, each linked to the place it was published; and
• votes cast directly on the site by verified members of the profession, each carrying cryptographic proof — that the voter was eligible, what they signed, and that the vote was accepted and logged — which anyone can re-check without trusting the site.

Konsensus is the platform underneath: the country-agnostic engine, protocol, and tooling in this monorepo that could run the same kind of index for another country or profession.

Counts describe the records admitted under one published instance policy, not the profession as a whole.

The reusable parts are also published standalone: konsensus (the country-agnostic frontend), qualified-opinion-protocol (the V3 protocol and offline verifier), gcs-attested-registration-voting (the Confidential Space registration/voting reference), and confidential-space-verify (offline attestation-token verification).

Repository layout

apps/web                          Hukukça Next.js application and public APIs
apps/worker                       queued crawl and recomputation worker
apps/confidential-email-verifier  Confidential Space email/passkey service
apps/transparency-witness-*       Cloudflare and GCP witness implementations
instances/                        signed instance policies
packages/proof                    canonical protocol, signatures, Merkle, tally
packages/proof-verifier           offline vote-proof verifier and CLI
packages/transparency-monitor     append-only log monitor
packages/db                       schema, migrations, queries, seed/import tools
infrastructure                    source-pinned infrastructure policies
scripts                           release, database, witness, and audit tooling
docs                              architecture and operator runbooks

Local development

Requires Bun 1.3 and Docker with Docker Compose.

bun install --frozen-lockfile
docker compose up -d --wait
cp .env.example .env
bun db:migrate
bun db:seed
bun dev

The web app runs at http://localhost:3000, PostgreSQL at localhost:55432, and Meilisearch at localhost:7700. To log in locally, open http://localhost:3000/giris and use the seeded administrator iletisim@hukukca.org / password. The password form only exists while development authentication is enabled; production refuses it.

Checks

The same non-database checks as CI:

bun repository:boundaries
bun typecheck
bun lint
bun test
bun audit

CI additionally exercises the database contracts on PostgreSQL 16 and 17; see .github/workflows/ci.yml.

Verifying a vote

Direct votes produce question-scoped public proofs that can be checked offline, without an application session or database. The core protocol package is dependency-free:

bun packages/proof-verifier/src/cli.ts \
  --bundle vote-proof.json \
  --policy verification-policy.json \
  --expected-policy-sha256 64_LOWERCASE_HEX_CHARACTERS

What the proofs do and do not establish — including the email, eligibility, and witness trust boundaries — is documented in docs/architecture.md, docs/confidential-email-verification.md, and docs/transparency-monitoring.md.

Production

Do not infer a production configuration from .env.example. The hosted release uses separate database roles, non-exportable Cloud KMS keys, attested workloads, exact release manifests, and guarded promotion and rollback. Start with docs/deployment.md and the other operator runbooks in docs/.

Contributing and security

See CONTRIBUTING.md and CODE_OF_CONDUCT.md. Report vulnerabilities privately according to SECURITY.md.

License

Source code is licensed under Apache-2.0. Original documentation and project-authored dataset structure are licensed under CC BY 4.0 unless stated otherwise. See LICENSE, LICENSE-DATA.md, and NOTICE.md.