Skip to content
SemHiel2003Public

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Once Upon a Doodle

Every drawing has a story.

Point your phone at a child's drawing. It becomes a narrated picture-book story you can play, keep on a shelf, and send to a grandparent — who never has to sign in to watch it.

Built from the Claude Design project Design Doc.dc.html. The design is the source of truth for every colour, size, radius, shadow and animation in here.

Running it

npm install
npm run dev      # http://localhost:5173 — also served on your LAN IP

The dev server binds to 0.0.0.0, so you can open it on a real phone on the same wifi. That is worth doing: the camera, the tap zones and the swipe gestures are built for a thumb.

npm run typecheck
npm run build     # tsc --noEmit && vite build

ElevenLabs narration is generated by a server-side worker; the Vite browser must never receive the API key or provider configuration. Copy .env.example into the server runtime's secret/configuration store (not a client .env file), set both pinned voice IDs, and follow the ElevenLabs bedtime narration guide for the endpoint, private cache, deployment, synchronization, and fallback flow.

The Vite development endpoint is not the production deployment. Before enabling remote narration in production, deploy the same-origin POST /api/narration/synthesize handler in a Node 20 server runtime, bind its authentication, story-ownership, rate-limit, durable cache, and private object storage adapters, and route /api/* to that runtime ahead of the SPA fallback. The bucket must reject public access; return authenticated media routes or short-lived signed URLs. The guide's production deployment checklist is the exact remaining server handoff.

The flow

/              splash (2.3s, once)
/camera        home — live camera or photo upload
/generating    beats and pages appearing while the story is written
/play/:id      the story player — narration, tap zones, swipe, page turns
/shelf         everything you have kept
/story/:id     one story: play, share, download, delete
/s/:shareId    the share page a grandparent opens. No login, ever.

Sign-in is never a gate. The "keep your stories safe" sheet appears exactly once, after the first story ends, and "Not now" is always there.

Layout

src/
  screens/       one file per route, each with its own CSS module
  sheets/        share · delete · sign-in, raised from anywhere via the store
  components/    DoodleArt (the crayon scenes), FrameArt, Icon, BottomSheet,
                 PhoneShell, Toast, SheetHost
  store/         useAppStore — zustand, persisted to localStorage
  services/      storyService (generation) · narration (text to speech)
  data/          seed stories + the mock generator's templates
  lib/           image capture/downscale, date formatting, ids
  styles/        tokens.css (the design system) + global.css (motion, utilities)

Design tokens live in src/styles/tokens.css and nowhere else. Components use the variables; raw hex only appears where the design uses a one-off value with no token, and inside SVG presentation attributes, which cannot read CSS variables.

Deploying it

The API must run as one long-lived Node process, not as serverless functions. Read this before choosing a host — the wrong choice gives you a live URL where generation never completes, which looks deployed and is not.

Story runs are held in process memory: InMemoryJobManager keeps job state in a Map (src/ai/jobs.ts), and rendered page bytes live in another Map inside RenderStore (src/server/storyProxy.ts). The browser creates a run with a POST and then polls it every 350ms. On any platform that spreads requests across ephemeral per-invocation instances, the POST lands in one instance and the poll lands in another, which has never heard of that run — the poll 404s forever and the images 404 with it. Nothing in the client is wrong; the state simply is not there.

So the API needs a host that keeps one process alive across requests — Render, Railway, Fly, or any plain Node host. The static bundle can be served from anywhere, including the same process.

vercel.json in this repo configures the static side correctly (deep links, caching) and is ready if the runs ever move to shared storage, but a static-plus-functions Vercel deploy will not work today.

The live target: Render

render.yaml is the blueprint. Two commands are the whole contract:

npm ci && npm run build   # typechecks client + server, emits dist/ and dist-server/
npm start                 # node dist-server/index.js

The server binds process.env.PORT (default 8080), serves dist/ with its own SPA fallback, and mounts the API on the same origin — so the host needs no rewrite rules at all. Deep links are handled in code. Verified by booting it: /, /s/:shareId and /play/:storyId all return the real SPA with a 200, and the hashed asset it references 200s cold.

Two things that will break a deploy if changed:

  • Keep node_modules at runtime. The openai SDK is loaded by dynamic import and deliberately not bundled, so it has to be on disk when the server runs. It is a production dependency, so npm ci --omit=dev is safe; deleting node_modules or shipping dist-server/ on its own is not.
  • Keep it at one instance. Run state lives in process memory, so a second instance answers polls for runs it has never heard of. render.yaml pins numInstances: 1 and says why.

Set the secrets first

Two are required; without them the app builds, serves, and then fails at the first model call:

Variable Used for
OPENAI_API_KEY vision, story, and illustration stages
ELEVENLABS_API_KEY narration audio

Set them under Project → Settings → Environment Variables for Production, Preview, and Development. .env.example documents these and the optional ELEVENLABS_* and NARRATION_* values.

Never give any of them a VITE_ prefix. Vite inlines VITE_-prefixed values into the bundle it ships to every visitor, which publishes the key permanently and readably. Every secret here is read on the server and never reaches the browser.

What vercel.json does

  • Deep links work. A rewrite sends every non-/api/ path to index.html, so /s/:shareId and /play/:storyId open directly — cold, in a stranger's browser, with no client-side history — instead of 404ing. The rewrite excludes /api/ so functions still route to functions.
  • The deployed build is never stale. index.html is served must-revalidate while hashed assets under /assets/ are immutable and cached for a year. A judge opening the link always gets the current build, and pays for the bundle only once.
  • Generation would need room to finish. Functions are declared with maxDuration: 300. A single illustration takes roughly 34 seconds and a story renders five, so the platform default of 10–15 seconds would time out every request. 300s requires Fluid compute (Pro); on Hobby the ceiling is 60 seconds and the pipeline does not fit. This applies only if the run-state problem above is solved first — the timeout is the second obstacle, not the first.

Shipping

Vercel's Git integration builds every push to main and promotes it. The workflow in .github/workflows/deploy.yml typechecks and builds alongside it, and asserts that no development-only route reached the production bundle — the one-button promise is easy to break by accident and a source grep misses it. That workflow only deploys when run manually with the deploy input set, so two systems never promote the same commit.

Where the backend plugs in

The UI is complete and runs entirely on the device today. Three seams are waiting:

Seam File Currently Next
Story generation src/services/storyService.ts staged local mock with three templates upload the photo, call the model, stream real beats and pages back through the same GenerationProgress
Narration src/services/narration.ts planned beat metadata with device speech fallback synthesize/cache one ElevenLabs clip per beat on the server and attach its URL to frame.audioUrl
Storage & auth src/store/useAppStore.ts localStorage, a fake signIn() real accounts, a synced shelf, and share links that resolve on any device

StoryService is a single interface with one implementation. Swapping in a remote one changes one line and nothing else in the app: no screen knows where stories come from.

Two things to know when that happens:

  • Story.shareId is generated on-device, so /s/:shareId only resolves for stories in this browser's own storage. SharePage already renders a warm not-found state for the case where it doesn't.
  • Story.status (generating · ready · failed) is carried through the model but nothing branches on it yet — a partially generated story would render as though it were finished.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages