KCLUB — KYLYVNYK CLUB

A closed international business club, delivered as a web application.

Verified members hold a digital membership card and get access to a catalogue of vetted partner businesses that offer them a discount. Members who own a business can pass warm client referrals to other member businesses. Everything is moderated, nothing about a member is public, and there is no member directory — by design, not by omission.

Status: design complete, phase 0 in progress. This repository currently contains the documentation set and the delivery plan; there is no application code yet. Start with docs/brief.md, then docs/requirements.md. What is being built right now is in docs/delivery/phase-0.md.

---

The shape of it in ten lines

• One Next.js 15 application on Vercel — marketing site, member area, staff console and card verification in a single deployment, organised as a modular monolith (ADR 0001)
• PostgreSQL 17 on Neon as the only datastore, through Drizzle (ADR 0002)
• Self-hosted phone authentication; SMS codes from Twilio Verify (ADR 0003)
• Stripe Billing as the system of record; entitlements projected from webhooks, never from a redirect (ADR 0004)
• Background work on Inngest, fed by a transactional outbox (ADR 0008)
• Three languages (en/ru/uk), light and dark themes, mobile-first, WCAG 2.1 AA

Two products, both $19.99/month: VIP membership and a partner catalogue listing.

---

The three constraints that shape everything

Read these before proposing a feature. Each has cost real design decisions, and each is the thing a newcomer is most likely to violate while building something perfectly reasonable.

1. No member is ever disclosed to another member. There is no member directory, no people search, no member-to-member messaging. The data layer has no function that returns a collection of members to a member-scoped actor, and a generated test walks the whole route table proving it. (ADR 0005)
2. Money and access must never disagree. Entitlements come only from Stripe webhooks, projected as a fold over state, reconciled nightly. A return from the checkout redirect grants nothing. (ADR 0004)
3. This is not MLM, structurally. No referral codes, no downline, no commission, no invite quotas. Referrals are client introductions between businesses, with recorded consent and a hard quota. (ADR 0009)

---

Running it locally

What works today. Node.js 22 LTS and pnpm 10 through Corepack:

corepack enable
pnpm install
pnpm dev                          # http://localhost:3000
pnpm verify                       # typecheck + lint + format

That is the whole of it, and the page it serves is a placeholder. There is no database, no authentication and no interface yet — the skeleton exists so that the checks, the hooks and the pipeline are in place before anything depends on them.

What does not work yet, and which task adds it: the database and migrations (T-0.9), Docker services (T-0.17), locales (T-0.14), the design system (T-0.15). Until then pnpm install is the only setup step. The full prerequisite list — Docker for PostgreSQL, Redis and MinIO, plus the Stripe CLI — is in CONTRIBUTING.md, which describes the finished state rather than the current one.

The target remains under 30 minutes from a clean machine; anything longer is a bug worth fixing. Current progress is in docs/delivery/phase-0.md.

---

Documentation

Everything about this project that is worth knowing is in docs/. Each document says at the top when it should be written and who owns it.

Before the first line of code

File	Answers the question
docs/brief.md	What problem, for whom, and what are we not doing?
docs/decisions/	Why is anything the way it is?
CLAUDE.md	What must be known before touching this repository, and where does each answer live?

Once the work outlives a prototype

File	Answers the question
docs/requirements.md	What must it do, and when is it done?
docs/delivery/	What is being built now, in what order, and what closes a phase?
docs/technology.md	Which technologies, and why these?
docs/architecture.md	How is the system structured?
docs/ux.md	What does the user see, and what happens when it fails?
docs/glossary.md	What do we call things — in code, in the UI, in the database, in three languages?
docs/data-storage.md	Where does data live, and how is it kept safe?
docs/testing.md	How do we know a change is safe to ship?
docs/legal-alignment.md	Where do the executed legal documents and this design disagree, and who decides?
CONTRIBUTING.md	How does work get merged and released?

Before the first production deploy

File	Answers the question
docs/security.md	What are we protecting, from whom, and how?
docs/reliability.md	What happens when something breaks?
docs/observability.md	How do we know the system is healthy?
docs/integration.md	What do we talk to, and what is the contract?

When more than one person maintains the documentation

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗