Matchids

A Digital World Where Children Learn, Imagine, Create and Give

Matchids is an international digital platform for children, parents and communities. It brings together a digital book library, a creative Kids Art space, and a Give Back program that supports children in orphanages who need it most — built on a modern web stack with both traditional and Web3 (CeloHT) payment support.

Founded by Suzie Matchilda George.

Learn · Imagine · Create · Give

---

Table of contents

• Vision
• The four pillars
• How the ecosystem fits together
• Repositories
  • Phase 1 — core product
  • Phase 2 — scale & reach
• Technology stack
• Payments — traditional & Web3
• Child safety & privacy
• Security principles
• Design language
• Content & honesty principles
• Getting started
• Development priority
• Contributing
• License

---

Vision

Matchids exists to give children a safe, warm, genuinely useful digital space — one that treats reading, creativity, and generosity as equally important, and treats parents as partners who deserve a platform they can actually trust.

The product is built around four pillars, and the engineering organization is built to protect them:

The four pillars

Pillar	What it means in the product
Learn	A digital library of free and premium books, organized by age, language and category
Imagine	Kids Art — coloring pages, creative prompts and activities
Create	A platform built to grow with real content and real features — never placeholders dressed up to look finished
Give	The Give Back program — directing part of what Matchids earns toward children in orphanages, reported only with real, verified data

How the ecosystem fits together

Matchids is deliberately split into many small, single-responsibility repositories instead of one monolith — each one independently buildable, testable and deployable, with sensitive logic (payments, database access) kept out of anything that ships to a browser.

matchids-web  ─────HTTP─────>  matchids-backend  ─────Prisma─────>  matchids-database
     │                              │
     │ imports tokens/components     ├── matchids-payments   (card payments)
     ▼                              └── matchids-celoht        (CELO / USDm on Celo)
matchids-design-system                    ▲
     ▲                                     │ implements the PaymentProvider
     │ imports tokens/components           │ interface from matchids-payments
matchids-admin  ─────HTTP─────>  matchids-backend (same instance)

matchids-content  ──(metadata + storage refs)──>  matchids-backend admin import path
matchids-mobile  ─────HTTP─────>  matchids-backend (same API as the website)
matchids-infrastructure  ── deploys and connects all of the above
matchids-security  ── audits and documents security across all of the above
matchids-docs  ── documents the entire ecosystem

No repo reaches into another's database or source code directly — every connection is either an HTTP call, a documented package dependency, or a shared interface contract.

Repositories

Phase 1 — core product

Repo	Responsibility
matchids-web	The public website — frontend only. Homepage, book library, Kids Art, Give Back, checkout, account, legal pages. Talks to matchids-backend over HTTP only.
matchids-backend	The API: authentication, users, books, categories, artwork, orders, payments, donations, donation campaigns, user library, notifications, admin. All business logic and payment verification lives here.
matchids-database	The canonical Prisma schema, migrations, seed data and modeling conventions every other service builds against.
matchids-payments	Provider-agnostic payment abstraction — one PaymentProvider interface that traditional card payments and Web3 payments both implement, so matchids-backend never talks to a specific processor directly.
matchids-celoht	The Web3 payment provider. CeloHT is a dapp that lets people send and receive CELO and USDm on the Celo blockchain — this repo implements matchids-payments' interface for it.
matchids-admin	The internal admin dashboard — manages books, categories, Kids Art, users, orders, payments, donations, donation campaigns, featured content and platform settings.
matchids-content	Content management — book and artwork metadata, validated against JSON schemas, kept separate from large binary files and from what's live in production.
matchids-design-system	Design tokens, a shared Tailwind preset, reusable UI components, and the brand assets (logo, favicons) every app builds on.
matchids-docs	Full documentation for the entire ecosystem — architecture, API reference, security, child safety, development guides.

Phase 2 — scale & reach

Built once the phase 1 foundation is solid, not in parallel with it.

Repo	Responsibility
matchids-infrastructure	DevOps — local dev stack (Docker Compose), CI/CD documentation, secrets management, monitoring, backups, scaling notes.
matchids-security	Threat model, security architecture, vulnerability management process, and the pre-launch security audit checklist.
matchids-mobile	The Android/iOS app (Expo/React Native) — uses the exact same matchids-backend API as the website, no separate mobile backend.

Technology stack

• Frontend: Next.js 14 (App Router), TypeScript, Tailwind CSS
• Backend: Express + TypeScript, PostgreSQL via Prisma ORM
• Mobile: Expo / React Native
• Payments: a provider-agnostic abstraction layer, with a card processor and CeloHT (Web3) as interchangeable providers
• Testing: Vitest (and supertest for the API)
• Deployable to any Node-compatible host

Payments — traditional & Web3

Card payments and Web3 payments are kept structurally separate but fully interchangeable from the backend's point of view — both implement the same PaymentProvider interface (isConfigured, createIntent, verifyTransaction, optional refund), defined in matchids-payments.

• CeloHT — a dapp that lets people send and receive CELO and USDm on the Celo blockchain — is treated as one payment provider among others, implemented in matchids-celoht.
• No payment is ever confirmed by the frontend. Every provider's verifyTransaction() re-checks with the real provider and only ever runs from trusted backend code (matchids-backend's webhook handler).
• No invented integration details, anywhere. No contract address, ABI, RPC endpoint, CeloHT API route, wallet address, or private key appears in any repo. Every provider reports isConfigured() === false honestly until real credentials exist, and the UI shows that payment method as unavailable rather than pretending it works.

Child safety & privacy

Because Matchids serves children, safety isn't a checklist bolted on at the end — it shapes the architecture itself:

• Every book and artwork entry moves through draft → in_review → published in matchids-content before it can reach real users.
• matchids-database's User model supports parent → child relationships, so parents manage child profiles rather than children holding fully independent accounts.
• Phase 1 has no open social features between users — no public profiles, comments, or messaging.
• Only the data needed to run the product is collected — no behavioral tracking, no third-party advertising targeted at child accounts.

Full detail in matchids-docs/security/CHILD_SAFETY.md.

Security principles

• Never trust a client-reported payment confirmation.
• Never expose private keys, secrets, or credentials — in code, in logs, or in a commit, anywhere in the organization.
• Validate and sanitize all external input; protect every API and admin route with real, server-side authentication and role checks.
• Rate limit sensitive routes; never leak stack traces in production.

Full detail in matchids-security.

Design language

Warm, playful without being childish; professional enough that a parent skimming pricing or a donation receipt trusts it. The palette (coral, gold, teal, violet on a warm cream background) is drawn directly from the brand mark — two figures forming an "M" around a book and a heart — paired with a rounded display typeface (Baloo 2) and a clean body typeface (Plus Jakarta Sans). Full rationale and usage rules in matchids-design-system/docs/BRAND.md.

Content & honesty principles

These rules apply to every repository, without exception:

• No invented data. No fake statistics, testimonials, partner organizations, orphanages, donation numbers, contract addresses, ABIs, or API endpoints — ever.
• No secrets committed, ever. Real credentials live only in local .env files, CI secret stores, or a hosting platform's secret manager — never in a repository, in any form.
• Unfinished features are represented honestly — a "coming soon" label, a documented integration point, an empty state — never faked to look more complete than they are.
• Content involving children is reviewed for age-appropriateness before it's merged or published.

Getting started

Full walkthrough: matchids-docs/development/GETTING_STARTED.md. Short version — clone in this order, since each depends on the ones before it:

git clone <org>/matchids-database
git clone <org>/matchids-design-system
git clone <org>/matchids-payments
git clone <org>/matchids-celoht
git clone <org>/matchids-backend
git clone <org>/matchids-web
git clone <org>/matchids-admin

Then follow each repo's own README for its specific setup steps.

Development priority

Phase 1 (matchids-web, -backend, -database, -payments, -celoht, -admin, -content, -design-system, -docs) comes first and is where current effort is focused. Phase 2 (matchids-infrastructure, -security, -mobile) is intentionally sequenced after — mobile in particular is not prioritized ahead of a solid, well-tested web foundation.

Contributing

See CONTRIBUTING.md in this repo for the rules that apply organization-wide, and each repo's own CONTRIBUTING.md / README.md for repo-specific setup. In short: never commit secrets, never invent data, and keep everything involving children age-appropriate.

License

Every Matchids repository is MIT licensed — see the LICENSE file in each one.