szabadpalya/SPEC.md

Szabadpálya — spec overview

Status: draft v0.7 — 2026-08-22 Working name: Szabadpálya · szabadpalya.hu Reference UX: reward-based crowdfunding, Kickstarter pattern

---

1. Positioning

Curated, invite-only crowdfunding platform for public projects: helyi szervezetek, Lepke-típusú kulturális egyesületek, szövetséges NGO-k.

Party-adjacent, not party-branded. The platform has its own name, identity and operating entity. Momentum's name, logo and colours do not appear in the product, the domain, or the legal footer. The connection is in who gets approved and who founded it — not in the branding. Practical consequences:

• Separate legal operator: a new egyesület, to be founded (see 1c).
• Own name and mark (see 1b). The visual world is shared with the Momentum rendszerbontó identity — palette, typography, motif — but the Momentum mark and wordmark never appear. Shared language, separate signature.
• Impressum names the egyesület. No "a Momentum kezdeményezése" line.

No campaign may fund a party, a party campaign, or a candidate. That boundary is what keeps the platform outside párttörvény (2007. évi CLXXXI. tv.) reporting and donation-cap rules, and it is enforced as an explicit check in the approval queue, not as a policy sentence.

Campaign creation is closed: creators apply, an admin approves. Main structural departure from the usual reward-crowdfunding model, which is open self-serve.

1b. Brand

Name: Szabadpálya · szabadpalya.hu (no DNS as of 2026-08-22 — verify at a registrar and register before any design work ships)

Tagline: Szabad a pálya. ("the track is clear")

From the living idiom "szabad a pálya!" — the coast is clear, go ahead, nothing is in your way. Exactly what the platform says to a public project waiting for a permission it never actually needed. Pálya also reads as track / field / career: young, forward-moving, unideological.

The name carries szabad openly. We are not concealing the political lineage — the platform is party-adjacent and that is fine — we are simply not dressing it in Momentum's identity. No Momentum logo, colours, typography or naming conventions. Szabadpálya has its own mark.

Visual basis: the Momentum rendszerbontó brand edition (../arculat/arculat3_assets/; the handbook PDF sits in brand/, gitignored).

Token	Value	Role
Electric purple	#7360F9	primary accent, CTA, progress lane
Lime	#B9D440	overshoot, emphasis, the arrow
Lavender	#BC9BF3	secondary chips
Cream paper	#FFF1EB	ground
Ink	#241C3B	text
Heritage purple	#8E6FCE	sparing; ties back to the older identity

Ratio per the handbook: cream + ink ~55%, electric ~25%, lime + lavender ~15%. Typography: Playfair Display (display serif) + Poppins (body). The handbook has no dark mode — the ink-grounded variant is our extension.

Logo: placeholder, in brand/out/. Three lanes, the middle one open, running into a lime arrow. Text is converted to paths, so it renders without the fonts installed. At 32 px the dimmed lanes wash out — a small-size variant is needed if this mark survives.

Voice (Hungarian UI copy): second person singular, active verbs, no NGO passive. Indíts kampányt, not Kampány indítása. Beleadom, not Támogatás.

Primary CTA vocabulary:

Context	String
Pledge button (tier)	Beleadom
Main campaign CTA	Beleadom ebbe a projektbe
Launch a campaign	Indíts kampányt
Browse	Nézd meg, mi épül
Hero	Szabad a pálya.

1c. Operator

A new egyesület, founded for this purpose. Not Momentum, not an existing organisation. Consequences to plan around:

• The domain, the mark and the Stripe platform account are all registered to the egyesület — not to a private person.
• Hungarian egyesület registration (törvényszék) takes weeks to months and needs 10 founding members, statutes, and a registered seat. Build can proceed in parallel; Stripe test mode needs nothing, live mode needs the registered entity, tax number and bank account. That is the real launch gate, not the code.
• Creators onboard as their own Connect accounts, so the egyesület never holds campaign money — it only operates the platform.
• With a 0% platform fee the egyesület has running costs (hosting, domain, mail) and no revenue from campaigns. Budget for it, or the "ingyenes" promise is the first thing to break.

2. Funding model

Keep-what-you-raise. Contributions are kept regardless of whether the goal is reached. The progress bar is motivational, not binding.

Fulfillment guard (mitigation)

Physical rewards + immediate charge = shipping debt if the goal misses. Charging is therefore decided per tier type:

Tier type	Charge timing	Rationale
donation (symbolic, no good)	immediate	Nothing owed in return
digital (PDF, credits listing)	immediate	Zero marginal cost to deliver
physical (book, print, bundle)	on goal reached, else released at close	Never owe a good you can't produce

If a campaign with physical tiers ends under goal, physical pledges are released uncaptured and the backer is notified; donation and digital money is kept. Config flag campaign.physical_tier_policy = guard | immediate.

Legal consequence

Charging for a shippable good is távollévők közötti szerződés under 45/2014. (II. 26.) Korm. rendelet — 14-day withdrawal right, ÁFA due at charge, mandatory pre-contract disclosures at checkout. Physical tiers must carry: seller identity, delivery deadline, total price incl. ÁFA and shipping, withdrawal notice. Donation tiers do not.

3. Payments and fees

No platform fee. 0%. application_fee_amount = 0 on every charge. The operator entity absorbs hosting and running costs; this is cost-recovery-free by design and is a headline selling point against the 4.5–14.9% the commercial platforms charge.

Stripe Connect (HUF), platform-as-facilitator:

• Each approved creator org onboards as a connected account (Express). KYC/AML is Stripe's responsibility — important given who stands behind the operator.
• Backer pays via Payment Intent with setup_future_usage so the card is vaulted; guarded physical tiers use manual capture, re-authorized at close.
• Money never touches the operator's bank account. Creator is merchant of record.
• Payout on Stripe's standard schedule, min. net 50 000 Ft threshold.
• Phase 2: bank transfer (átutalás) with manual reconciliation for large donors.

Stripe's own processing fee is unavoidable and is deducted from the creator's payout — we cannot zero that out, only our own cut. The /dijszabas page must state this plainly so "ingyenes" is not read as "the creator receives 100%". Verify current Stripe HU card rates before publishing that page; do not hardcode a number in the product from memory.

Open: offer backers an optional "fedezem a tranzakciós költséget" checkbox at checkout? Common on NGO donation flows, keeps creator payout whole. Not MVP-blocking.

4. Page inventory

4.1 Campaign detail — /kampanyok/:slug

1. Header — category chip, title, creator avatar + name, Kedvencekhez adás
2. Media gallery — carousel, image counter 1/10, video support
3. Funding bar — Cél: X Ft · Összegyűlt: Y Ft · N% progress · N támogató · N nap van hátra · status badge
4. Sticky CTA — Beleadom ebbe a projektbe, Megosztás, Megfigyelés
5. Tabs — Sztori · Frissítések · Hozzászólások
6. Story — rich content (Összefoglalás, Bemutatás), A csapat bios
7. Reward tiers — see 4.2
8. Footer

Desktop: story left, sticky tier rail right. Mobile: single column, funding bar and CTA pinned to viewport bottom.

No Támogatók tab. The commercial platforms publish a backer list; we do not. Backer identities are never public — not by name, not by avatar, not opt-in. Consequences:

• The aggregate count stays (164 támogató) — non-identifying and load-bearing for social proof.
• Full backer list is visible only to the campaign creator in /vezerlopult, and only for fulfillment. Never exportable to a general-purpose mailing list.
• The 100 000 Ft reference tier's "name printed in the credits" perk still works — that is the creator's own publication, not platform-published data.

Rationale: a donor list attached to a party-adjacent platform is both a GDPR exposure and a political liability. Not collecting public consent at all is cleaner than managing it.

4.2 Reward tier card

[ -20% ]  [ Legnépszerűbb ]
12 000 Ft   ~~15 000 Ft~~
Könyv és művészi nyomat
· 1 db könyv
· 1 db A4 művészi nyomat
14 támogató · 20 db-ra limitálva
Várható szállítás: 2026-11-30
[ Beleadom ]

Fields: price, list_price?, title, includes[], backer_count, inventory_limit?, estimated_delivery, is_featured, type (donation | digital | physical), requires_shipping.

4.3 Other pages

Route	Purpose
/	Landing: featured campaigns, how-it-works, social proof
/kampanyok	Browse — filters Összes / Aktív / Legnépszerűbb / by category
/kampanyok/:slug/tamogatas	Checkout: tier → qty → shipping → Stripe → confirm
/sikersztorik	Completed campaigns
/hogyan-mukodik	Explainer
/dijszabas	Zero platform fee + honest note on Stripe processing costs
/belepes, /regisztracio	Auth
/vezerlopult	Creator dashboard: editor, backers (private), updates, payouts
/admin	Approval queue, moderation, political-content screening

5. Domain model

User ──< Campaign ──< RewardTier ──< Pledge >── User (backer)
             │                          │
             ├──< Update                └──< ShippingAddress?
             ├──< Comment
             └──< Payout

Campaign: slug, title, category, creator_org, goal_amount, currency=HUF, starts_at, ends_at, status (draft → beadva → aktiv → finanszirozott / lezart / elutasitva), story (rich), media[], team[], physical_tier_policy.

Pledge: backer, tier, quantity, amount, stripe_payment_intent_id, status (authorized | captured | released | refunded), shipping_address?. No is_anonymous field — every pledge is private, so there is nothing to toggle.

Derived, never stored: raised_amount, backer_count, progress_pct, days_left. Computed from captured + authorized pledges so the bar cannot drift from reality.

6. Campaign duration

The creator picks a concrete end date, not a length in days. It is shown as a date everywhere in the creator UI (A kampány eddig tart: 2026-11-30) and rendered as a countdown only on the public page (9 nap van hátra).

• Bounded: ends_at must fall within 90 days of launch. Configurable ceiling, enforced server-side at submit and at launch approval.
• Campaigns close at 23:59:59 Europe/Budapest on the chosen date, not at the wall-clock instant of launch — a Hungarian creator picking "november 30" means the whole day.
• Extension after launch: admin-only, and never past the 90-day ceiling. Creators cannot quietly move their own deadline once money is in.
• estimated_delivery on physical tiers must be after ends_at. Validated.

7. Key flows

Back a project — tier select → qty → shipping (if requires_shipping) → account or guest email → Stripe Payment Element → confirm → receipt email. No public trace.

Campaign close — scheduled job at ends_at: evaluate goal → capture guarded physical pledges or release them → notify backers → notify creator → open the fulfillment view in /vezerlopult.

Creator apply — form → admin review (incl. explicit political-content check) → Stripe Connect onboarding → editor unlocked → submit for launch approval.

8. Stack

Self-hosted on our own managed server. Everything below runs on one box under Docker Compose; nothing depends on a PaaS.

Two languages, on purpose. The stack was TypeScript end to end until the backend was rewritten in Go; the original argument (one language, one dependency tree) was sound and is now overridden by a deliberate decision. What it costs is recorded honestly below, because the reasoning that produced this table should not have to be reconstructed from a diff later.

Application

Layer	Choice	Why
Backend	Go + Gin, single static binary	One process serves the API, the HTML document, the share images and the built assets. 49 MB image, nothing to install.
Frontend	React 19 + React Router + Vite	The campaign pages were already components; only their data source changed.
HTML document	Go html/template	Per-campaign og: tags without a JS runtime — see below.
DB	Postgres 17, same host	Tiny dataset. No managed service needed at this scale.
Data access	pgx + hand-written SQL	The three queries that matter are aggregates over pledges; SQL states them more plainly than an ORM did. Migrations are plain .sql applied by a ~60-line runner.
Auth	Own magic links (api/internal/auth)	Go has no better-auth. ~200 lines: hashed tokens, single-use redemption, cookie sessions.
Share images	Drawn in Go (api/internal/ogimage)	Go has no Satori. Rectangles and text on a 1200×630 canvas.
Editor	Tiptap	Campaign story rich text. Not built yet.
UI	Tailwind 4, rendszerbontó tokens	See 1b.
Proxy/TLS	Caddy	Automatic Let's Encrypt, two lines of config.
Deploy	Docker Compose on the box	db, migrate, app. Nothing depends on a PaaS.

What the second language costs. Money code loses Stripe's TypeScript types, which this document previously called the best guardrail available for it — Go's Stripe library is typed but less expressive about the shapes Stripe actually returns. Payments are still unbuilt (section 2 of TODO.md), so that cost lands in full on the work that has not started yet. Nothing about the rewrite makes it easier; it is a price paid for the rest of the stack.

Why the server renders HTML: the commercial Hungarian platforms are client-rendered SPAs — fetching a campaign page returns a ~3 KB empty shell, and the real content only exists after JavaScript runs. Every campaign shared to Facebook therefore shows the same generic site-wide card instead of the project's own photo, title and progress. For a platform whose growth is sharing, that is a permanent self-inflicted wound and the cheapest place for us to be strictly better.

Go renders the document, React renders the page. The seam is sharp: Go owns <head> — title, description, og: tags, the theme script, and the hashed asset tags read out of Vite's manifest.json — and React owns everything inside #root. Nothing is rendered in two places, so nothing can drift.

What this does and does not buy, stated plainly. It buys the share cards, which is the harm named above: crawlers read og: tags without executing JavaScript. It does not buy what full SSR bought — the campaign page no longer ships ~56 KB of real HTML, and a reader with JavaScript off sees nothing. Most of the practical difference is clawed back by inlining the data the server already loaded to build the tags, in a <script type="application/json" id="__DATA__"> block the client reads once; the first paint still waits for the bundle. If body text in the HTML ever turns out to matter for search, that is the point at which to reconsider, and the honest answer will be a JS runtime, not more Go templating.

What self-hosting makes our problem

These are load-bearing for money, not just uptime:

• Stripe webhooks need a reliably reachable HTTPS endpoint. Stripe retries, so handlers must be idempotent (dedupe on event.id) and must verify signatures. Extended downtime during a campaign close means captures do not happen.
• The close job (ends_at → capture or release) runs as a systemd timer or a small worker container, not Vercel Cron. It must be idempotent and safe to re-run: never double-charge a pledge.
• Backups are the real risk. Nightly pg_dump, encrypted, shipped off the box, with a restore actually tested. The DB holds pledges, addresses and a private donor list — losing it is worse than downtime, leaking it is worse still.
• Do not self-host SMTP. Use Resend, Postmark or SES for transactional mail. A small VPS sending receipts lands in spam, and payment receipts must arrive.
• Monitoring: uptime check (Uptime Kuma / healthchecks.io) plus Sentry. A dead-man switch on the close job matters more than CPU graphs.
• Media on a mounted volume, included in the backup set. Object storage (Hetzner/R2/MinIO) only if volume grows.
• Migrations run as their own step, not on app boot: compose.yaml has a migrate service (Dockerfile target migrator, the same image running server -migrate) that runs once and exits; app waits for it to succeed. The server refusing to migrate at boot is load-bearing, not tidiness — a process that exits when Postgres is unreachable can never report that Postgres is unreachable, and one blip would take the site down instead of degrading it.

Server placement

Host in the EU but outside Hungary — Frankfurt or Helsinki. The database holds a private list of who funded which public project; for a party-adjacent platform that is politically sensitive data, and Hungarian-jurisdiction infrastructure is more exposed to Hungarian pressure than German-hosted infrastructure is. This is a threat-model decision, not only a GDPR one. Full-disk encryption on the box, encrypted backups.

Known gotchas

HUF in Stripe does not follow the plain smallest-unit rule most currencies use. Verify current Stripe behaviour for forint before writing any money code, and store every amount as an integer with an explicit documented unit — never a float. (In the schema goalAmount, price and amount are all Int, forint.)

The Vite manifest is a boot dependency. The Go server reads web/.vite/manifest.json at startup to find the hashed entry files. build.manifest must stay on in vite.config.ts; without it the server refuses to boot rather than serving a document with no script tag.

Share tags are not exercised in development. Vite owns index.html there and the Go document template only runs in the container, so a broken og: tag will look fine locally. The CI container smoke test is the only thing that catches it — that is why it asserts the tags, the PNG magic bytes and the inlined payload rather than just a 200.

No live database at build time. The image build compiles Go and bundles the frontend; neither touches Postgres. The seed and the migrations are separate binaries run against a live database afterwards.

The seeder is not in the shipping image. It starts by deleting every campaign, organisation and user, so it lives in api/test/ and is built only by the seeder Dockerfile target, which --target runner never reaches. CI asserts the runner image does not carry it.

Intl and Go disagree about spaces. Intl.NumberFormat("hu-HU") groups digits with U+00A0, so api/internal/hu uses the same character. A plain space there would make the share card's numbers differ from the page's.

9. Out of scope for MVP

• AI Kampány Varázsló — AI-generated campaign drafts. Post-MVP.
• Post-campaign marketplace — selling the product after the campaign. Not planned.
• Bank transfer payments (phase 2).
• English localization (scaffolded, not translated).

10. Open questions

1. Optional "cover the transaction cost" checkbox at checkout — yes or no?
2. Category taxonomy — reuse the conventional set (Kultúra & Művészet, …) or define our own?
3. Does the placeholder logo stay, or does a designer take it over before launch?
4. Who funds the egyesület's running costs, given the 0% fee?

Resolved: name (Szabadpálya), operator form (new egyesület), funding model (keep-what-you-raise + fulfillment guard), fees (0%), payments (Stripe Connect), backer privacy (never public), duration (creator-picked end date, 90-day ceiling), visual system (rendszerbontó arculat, own mark).