Skin Signal

Your skin, decoded. Your next move, decided.

Comment

Inspiration

What it does

How we built it

Challenges we ran into

Accomplishments that we're proud of

What we learned

What's next for Skin Signal# SkinSignal

Understand your skin. Know what to do next.

Inspiration

Every skin-analysis demo we'd used stopped at the same dead end: a score, a handful of percentages, maybe a colorful chart — and then nothing. You're left standing there with a number and no idea what it actually means for your morning, your shopping cart, or the wedding you have tomorrow.

That gap was the whole idea. The YouCam Skin AI API gives you an extraordinarily capable read on a face — texture, oiliness, redness, pores, dark circles, a dozen other markers scored with real computer vision. But a score is not a decision. We wanted to build the layer that sits on top of the analysis and actually closes the loop: here's what's going on, here's what to do about it today, and here's why.

So instead of building "a skin analysis app," we set out to build a skin decision assistant — something that reads a scan the way a knowledgeable friend would, folds in your actual context (what you're trying to do, what event is coming up, how much time you have), and hands you a plan instead of a spreadsheet.

What it does

Upload a selfie — or capture one live through the webcam — and SkinSignal:

  1. Runs it through YouCam's real Skin AI pipeline (file upload → async task → polling, against their actual documented v2.0 API contract) and normalizes the raw output into a SkinSignal Score and a set of human-readable priority concerns.
  2. Feeds that scan, plus your stated goal ("prepare for an event," "improve my routine," "something changed"), into a LangGraph agent that produces a structured action plan — a morning routine, an evening routine, things to avoid, and a plain-language why behind every call.
  3. Deterministically ranks a local product catalog against your specific concerns, and answers the killer question: "Should I buy this?" — an AI Match Score with concrete reasons and honest considerations, not marketing copy.
  4. Tracks scans over time so you can ask "What changed?" and get a cautious, non-causal read on what might be contributing (new product, stress, sleep, sun exposure) — never a diagnosis, always hedged language.
  5. Links matched products out to Amazon, with an affiliate tag slot wired in so the recommendation engine can also become a small revenue stream.

It ships with two frontends: a fast, functional Streamlit app for reliability, and a second pass — a bold, dark, gradient-and-glass Next.js site with a real WebGL 3D hero (floating distorted glass forms built with React Three Fiber), because in a beauty-tech product, the interface is part of the pitch.

How we built it

Backend: FastAPI + SQLAlchemy/SQLite, with Pydantic schemas enforcing a strict boundary — YouCam's raw response never reaches the frontend, only our normalized SkinAnalysis model does. A deterministic mock mode mirrors the real API's shape exactly, so the whole demo runs reliably with zero external credentials when needed.

The agent: a five-node LangGraph graph — Context Analyzer → Concern Prioritizer → Action Planner → Product Recommender → Explanation Node — but only one of those nodes ever calls an LLM (Groq by default, with OpenAI/Anthropic as drop-in alternatives). Everything else — prioritization, scoring, comparison — is plain deterministic Python. If no LLM key is configured, a rule-based fallback plan kicks in automatically, so a missing API key degrades gracefully instead of breaking the demo.

Product intelligence: a 24-item local catalog and a fully deterministic scoring function (severity × concern match + goal relevance). The LLM is never allowed to invent an ingredient, a benefit, or a price — it only gets to explain facts the backend already knows to be true.

Frontend, round two: once the core loop worked, we rebuilt the experience in Next.js/TypeScript with Tailwind, Framer Motion, Zustand for shared state, and a hand-built Three.js hero scene — plus a capture flow that lets you either upload a file or open a live webcam feed and grab a frame straight into the same analysis pipeline.

Challenges we ran into

  • Reading the real API instead of guessing it. The spec was explicit: never invent an endpoint. So before writing a line of integration code, we pulled Perfect Corp's actual developer docs — auth scheme, base URL, the SD/HD dst_actions split, the async upload → task → poll lifecycle — and built against that contract exactly, including the image-quality gate (face must fill roughly 60–80% of frame width) that later explained a "rejected" test photo that looked perfectly fine to a human.
  • A debugging mystery that turned out to be a phantom backend. For a long stretch, every request came back {"detail":"Not Found"} no matter what we fixed. It took building genuinely self-diagnosing infrastructure — a custom 404 handler that lists real routes, forced unbuffered logging, a live backend-connection indicator in the UI, a "technical details" panel surfaced right in the error message — to finally reveal the actual cause: an unrelated local service had quietly claimed the same port. No amount of code changes would have fixed that; better diagnostics did.
  • A filesystem that didn't like Node. Building the Next.js app inside a synced project folder caused npm install to fail with obscure ENOTEMPTY rename errors. The root cause turned out to be a FUSE-mounted filesystem that couldn't handle npm's atomic rename dance — solved by building and verifying on a real local disk and shipping only clean source files.
  • Staying disciplined about what the LLM is for. It's tempting to let a language model touch everything. We kept coming back to one rule: the LLM interprets and explains; it never originates a fact. That discipline is what makes "AI Match Score" and "Purchase Match" feel trustworthy instead of like a random number generator with good copywriting.

Accomplishments we're proud of

A full YouCam Skin AI integration built against real documentation, an agent architecture that fails safe instead of failing loud, a product-matching system where every claim traces back to actual catalog data, and two complete, polished frontends — one built for speed, one built to make a judge stop scrolling.

What we learned

The real product was never the scan — it was the decision downstream of it. And the fastest way to debug a stubborn issue isn't more guessing, it's building the tool that shows you the truth (a log line, a route list, a live status check) instead of asking a person to describe it to you secondhand.

What's next

A full history/compare timeline in the new site, real ASIN-level Amazon product links once we have affiliate access, HD-tier skin concerns, and — per the hackathon's own roadmap — growing from skincare into the wider Perfect Corp ecosystem: makeup recommendations and apparel try-on, so "know what to do next" eventually covers the whole look, not just the skin underneath it.

Built With

Share this project:

Updates

Submission history