YSK product · MIT · npm · v1.0.1
Contracts first
@ysk-kit/contracts is the only source of enums, DTOs, error codes, and ts-rest routes. Do not use TypeScript enum.
MIT v1.0.1Free to use yourself
6 flavorssaas · desktop · gateway …
16 capabilitiesauth · jobs · billing …
10 examplesclinic · CRM · work orders …
Write business rules on day one
This repository is the living saas flavor. Identity, files, notifications, jobs, mail, API keys, crypto, and realtime are already wired. Product domains stay out of the kit.
- Scaffold
pnpm create @ysk-kit/app - Databasemigrate · seed
- Module
ysk-kit add module - Verify
pnpm layers· test - DevelopAPI :3001 · Web :5173
apps/web ──► @ysk-kit/web-sdk ──► @ysk-kit/contracts
▲
apps/api (HTTP adapter) ──────────────┤
│ │
▼ │
application / use-cases ─────────────┤
│ │
▼ │
domain (entities, ports) ────────────┘
▲
│ implements
infra (prisma, redis, s3, mail)
Hexagonal API
The business core does not know Express, Prisma, or React. Domain and application depend on ports. pnpm layers enforces this.
One HTTP surface
Browsers, phones, partners, and agents share REST + OpenAPI. Clients talk to the API only through @ysk-kit/sdk.
Optional capabilities
Auth, jobs, and billing are not required in every product. Thin strips llm / billing / orgs / push; add them back when you need them.
| Area | What you get |
|---|---|
| Scaffold | pnpm create @ysk-kit/app; from this checkout pnpm --filter @ysk-kit/create-app start |
| Flavors | saas, desktop, gateway, php-bridge, trading, static-web3 |
| Preset | Default thin; full keeps the living demonstration |
| Database | Prisma 7, MySQL default; --db postgresql|sqlite |
| HTTP | Express 5 default; HTTP_ADAPTER=fastify |
| Envelope | { ok, data } / { ok, error }; four documented exceptions |
| Clients | Vite 8 + React 19; Expo 57; Electron 44 |
| CLI | ysk-kit / yskk: add module, add capability, upgrade, check agent |
| Examples | Ten overlays: clinic, CRM, stock, tickets… |
| Guardrails | ysk-kit upgrade refreshes law / skills / TypeScript / Biome; check agent flags enum, client Prisma, raw fetch |
| Default ports | API 3001 · Web 5173 · Admin 5174 · OpenAPI /docs |
| Ops | Compose + PM2; optional Jaeger / Prometheus / Grafana |
Flavor selects which apps are copied
--flavor picks apps; --preset then thins optional capabilities. php-bridge and static-web3 ignore preset.
| Flavor | What you get |
|---|---|
saas | API + web + admin + optional mobile |
desktop | API + Electron |
gateway | API + admin (machine API keys ysk_live_…) |
php-bridge | OpenAPI + TypeScript / PHP clients, no Node apps |
trading | API + web + worker |
static-web3 | Vite web only |
saas
- Public web, operator admin, optional Expo, one API
--no-admin/--no-mobileapply; so do--presetand--db- Default flavor
desktop
- Electron talks to the same API through
@ysk-kit/sdk(platform: desktop) - Prisma stays in the API process, including localhost SQLite
- Tokens can use Electron
safeStorage
gateway
- Machine clients plus an operator console; admin is always copied
- Mint keys with
POST /v1/me/api-keys, thenAuthorization: Bearer ysk_live_… - Writes
GATEWAY.md
php-bridge
- Does not copy this monorepo. Emits OpenAPI plus envelope-aware TypeScript and PHP clients
- Point them at an existing Kit API. Remaining paths use generic
request() - Ignores preset and database flags
trading
- API + web + the existing BullMQ worker
- Market data and exchange connectors stay in the product
- Writes
TRADING.md
static-web3
- Vite web and
@ysk-kit/*client libraries only. No Prisma, noDATABASE_URL - Point
API_PUBLIC_URLat a remote API if the UI needs one - Wallet libraries belong in the product. Writes
WEB3.md
A capability is a platform feature; a module is a business slice
ysk-kit add <name> merges a catalogued capability. ysk-kit add module writes one hexagonal HTTP slice. Do not confuse the two.
Present after thin
- Identity (register, login, OTP, refresh, users)
- Files / storage, notifications, jobs + mail
- API keys + crypto, realtime (Socket.IO)
- Thin strips:
llm,team(organizations),billing,push(devices) - Restore with
pnpm ysk-kit add llm|team|billing|push.billingneedsteamfirst
Capability catalogue
| Name | What it adds |
|---|---|
auth | Session / OTP Prisma, JWT, OTP TTL, optional Twilio |
rbac | Permissions already live in ROLE_PERMISSIONS |
audit-log | Audit Prisma fragment |
storage | FileObject, S3_*, @ysk-kit/storage |
i18n | Default locale zh-HK |
jobs | Redis + BullMQ; in-memory queue when REDIS_URL is unset |
mail | SMTP; log adapter when empty |
notifications | In-app notification routes |
llm | Chat Completions; copies a source tree |
websocket | Socket.IO realtime |
push | Devices + Expo / FCM |
mobile | Points at the Expo template |
team | Organization + Membership (alias org) |
apikey | ApiKey fragment |
crypto | AES-256-GCM, CRYPTO_MASTER_KEY |
billing | Stripe Checkout; needs Organization first |
ysk-kit add module
- Name matches
^[a-z][a-z0-9-]*$. URL is/v1/<name> --prismamerges a title / body / authorId model- Writes contracts DTO + ts-rest, domain port, application, infra (memory + Prisma), SDK, web-sdk, Vite page
- A second run on the same name is a no-op
- Then edit Prisma fields, put rules in
application/, and runpnpm db:migrate && pnpm gen:openapi
Contracts, layers, and the envelope
Humans and AI agents follow the same path: scaffold thin, add a module, fill application/ and Prisma, then verify with pnpm layers.
JSON envelope
- Success
{ ok: true, data }; failure{ ok: false, error }. Pagination lives insidedata - Error
codevalues live in contracts (VALIDATION_FAILED,UNAUTHENTICATED,NOT_FOUND…) - Four exceptions:
POST /v1/llm/streamSSE; invoice PDF HTTP 302;GET /docsHTML;GET /openapi.json
Default stack
| Layer | Default |
|---|---|
| Monorepo | pnpm 12.8.1 + Turborepo 2 |
| Language | TypeScript 6 strict + exactOptionalPropertyTypes |
| Web / admin | Vite 8 + React 19 + TanStack Router / Query + Tailwind 4 |
| Mobile | Expo 57 |
| Desktop | Electron 44 |
| HTTP | Express 5; Fastify 5 optional |
| Contract | ts-rest + Zod 4 |
| Database | Prisma 7 (MySQL default) |
| Auth | JWT + refresh; email/password and +852 OTP |
| Observability | Prometheus GET /metrics; optional OTLP / Jaeger / Grafana |
@ysk-kit packages
contracts·domain-kernel·applicationapi-http·api-express·api-fastifysdk·web-sdk·ui·ui-logicauth·apikey·cryptojobs·mail·storage·i18nllm·push·realtime- The daily path is copy-tree +
ysk-kit upgrade, not installing registry@ysk-kit/*into the destination product
Hard rules
- Clients must not import Prisma, Express, Fastify,
@ysk-kit/auth, jobs, mail, push, or the AWS SDK - The API must not import React or
@ysk-kit/ui - CI uses in-memory ports. It does not start Redis, Stripe, Twilio, FCM, Jaeger, or Grafana
- Hono, Nest, Next, Drizzle, tRPC, and GraphQL are not defaults
Generators and guardrails
From npm: pnpm create @ysk-kit/app. From this checkout: pnpm --filter @ysk-kit/create-app start. YSK_ROOT selects which product tree the CLI patches.
create-ysk-app
- Flags:
--preset thin|full,--db mysql|postgresql|sqlite,--flavor,--no-admin,--no-mobile,--yes - A TTY prompts for omitted choices; CI / pipes never prompt
- From npm it downloads
yanshekki/ysk-kitat tagv{version}
ysk-kit / yskk
add module <kebab> [--prisma] [--web]add <capability>generate openapi(same aspnpm gen:openapi)upgrade [--dry-run]: copy allowlisted law, skills, TypeScript / Biome,pnpm layerscheck agent: flag TypeScript enum, Prisma in clients, rawfetch(
Ten worked examples
clinic-booking·crm-contacts·inventory-stock·helpdesk-tickets·membership-clubcourse-enrollment·invoice-quotes·event-rsvp·job-board·field-work-orders- Apply:
pnpm --filter @ysk-kit/examples start apply clinic-booking --yes - Overlays land on a new product directory; they are not mounted in this kit
Verify a change
pnpm layers && pnpm typecheck && pnpm test && pnpm gen:openapi && pnpm ysk-kit check agent- Seed accounts:
[email protected]/ysk-admin-dev(see.env.example)
Clinic-booking screenshots and a fast install
The five shots below are the real clinic-booking UI (1280×800), not invented admin chrome. Concept art is labelled separately.
02
Empty list
Module page: list + create on the same Zod schema. Real screenshot.
03
Validation
Overlapping SCHEDULED slots are rejected. Real screenshot.
04
Created
One appointment row inside the envelope. Real screenshot.
05
OpenAPI
GET /docs Scalar UI. Real screenshot.
06
Modules lock
Capabilities and flavors interlock like hex tiles. Concept art.
07
Layers
Contracts, application, infra. Concept art.
08
Surfaces
Web, phone, desktop, and gateway share contracts. Concept art.
Quick commands
- Scaffold (thin · MySQL · saas)
- Install · env · database
- Generate / migrate / seed
- Add a module →
pnpm dev
pnpm create @ysk-kit/app my-product --preset thin --db mysql --flavor saas
cd my-product
pnpm install
cp .env.example .env
docker compose up -d mysql
pnpm db:generate && pnpm db:migrate && pnpm db:seed
pnpm ysk-kit add module appointment --prisma --web
pnpm gen:openapi
pnpm dev
# API http://127.0.0.1:3001 · Web :5173 · Admin :5174Need a scaffold, white-label, or a custom build? See Business — no prices on this page.
Open source to use yourself; YSK can scaffold or custom-build
YSK Kit is published under MIT. YSK Limited can scaffold a product, add modules and capabilities, white-label AppShell, or custom-build from the kit — no fee for open-source use; custom work is quoted in writing.
Use it yourself
For self-serve scaffold, internal trials, and open-source work.
- Contract-first monorepo + CLI
- Install with
pnpm create @ysk-kit/app - No fee for that use
YSK scaffold / custom
For teams that need a flavor chosen, white-label, production, or a PHP bridge.
- The host stays yours — not multi-tenant cloud SaaS
- Hong Kong company contract; NDA when needed
- No custom prices on this page; the written quote wins
A new product in fifteen minutes
Pick a flavor and database; get a runnable API / web / admin.
You already have PHP or OpenAPI clients
php-bridge emits envelope-aware TypeScript and PHP clients.
Web + phone + desktop
One contract set. Vite, Expo, and Electron all go through @ysk-kit/sdk.
Ship on a host you own
Compose + PM2; optionally onto YSK Server.
| Custom scope | Notes |
|---|---|
| Scaffold | Node 24, pnpm 12, flavor / preset / database, first migrate / seed, pnpm dev |
| Modules and capabilities | add module, llm / team / billing / push, fields and business rules |
| White-label | AppShell name, mark, default locale zh-HK / en |
| Flavor cut | Gateway keys, desktop Electron, php-bridge, trading worker, static-web3 |
| Production | Compose, PM2, reverse proxy, optional YSK Server |
| Training | Contracts first, envelope, pnpm layers, agent skills |
| After delivery | Docs, remote training, warranty window. Small follow-ups can use outsourcing monthly tech tickets |
How we work
From enquiry to warranty, every step has a written scope. Open-source download and scaffold / custom work are billed separately.
- EnquireWhatsApp or email: the product, flavor, database, whether you need mobile / desktop
- DiscoverRemote call: compliance, white-label, existing systems, php-bridge
- ProposeScope, timeline, deliverables (scaffold vs custom modules); written quote
- ContractHong Kong company; NDA when needed
- Scaffold / buildFrom YSK Kit; staged demos
- AcceptAPI callable, web / admin sign-in, docs, training
- WarrantyDefects in the agreed window; then maintenance or outsourcing tickets
Deliverables (by contract)
- A runnable product tree (your host or the delivered repo)
- Deploy and ops docs; remote training
- Defect fixes in the agreed window
- MIT core stays MIT; custom-module IP follows the contract
Honest limits: YSK Kit is not multi-tenant SaaS. YSK does not turn your product into YSK cloud. Industry domains stay in the product repo. CI does not start Redis / Stripe / Twilio by default. YSK does not apply for cloud accounts on your behalf.
Business FAQ
Yes. MIT licensed for you to install. YSK does not charge for that use. Scaffold and custom work are quoted by scope.
Flavor, modules, white-label, and production vary widely. The written proposal is the quote. Small follow-ups can use existing outsourcing monthly tech tickets; larger work is a project.
No. The product still runs on a host you own or the contract names. YSK does not operate a multi-tenant cloud edition of YSK Kit.
Frequently asked questions
Direct answer: Yes. MIT licensed for you to install. Scaffold or custom work: see Business. No prices on this page.
Direct answer: Omni is a local-model gateway. Server is a single-host Linux control plane. Kit is the contract-first platform you scaffold a new product from.
Direct answer: Node.js 24 and pnpm 12. Default ports: API 3001, web 5173, admin 5174.
Direct answer: Thin (default) strips llm, billing, organizations, and push. Full keeps the living demonstration. Restore with pnpm ysk-kit add.
Direct answer: No. Product domains stay in the product repository. The ten examples are overlays applied onto a new directory.
Direct answer: No. The product still runs on a host you own or the contract names. YSK does not operate a multi-tenant cloud edition of YSK Kit.
Start with YSK Kit
MIT · YSK Limited. Contract-first. Scaffold a product in fifteen minutes. Scaffold or custom work quoted in writing.