Building PsycheGarden: A Production-Ready Wellness PWA with Context-Aware AI

Why PsycheGarden?

Most wellness tooling is either too clinical or too generic. PsycheGarden started with a simple product idea:

"What if mental load felt visible and intuitive, like tending a garden?"

So we built a deployable, context-aware web app that translates cognitive load into atmosphere:

• Blooming -> Stable -> Drained -> Burnout
• Real weather context
• Optional public world pressure context
• Optional research nudges
• Optional LLM guidance
• Full fallback behavior for reliable demos and uptime

Stack and Engineering Constraints

Frontend

• React + TypeScript + Vite
• CSS/SVG scene composition (no heavy 3D)
• PWA shell and offline support

Backend

• Node + Express
• API orchestration layer for context and insights
• Strong fallback-first design

Deployment

• Docker multi-stage image
• Google Cloud Build + Cloud Run

Core Architecture

Energy Model Design

The vitality score is intentionally transparent and tuneable.

const base = 52;
const sleepBoost = (signals.sleepHours - 6) * 6;
const stepsBoost = (signals.steps / 1000) * 2.2;
const screenPenalty = signals.screenTime * 3.8;
const meetingPenalty = signals.meetingLoad * 5.2;
const stressPenalty = signals.stressEvents * 8;
const recoveryBoost = signals.recoveryActions * 7;

Why this works for hackathon + product demos:

• easy to explain
• deterministic
• visibly reactive
• balanced for positive and negative events

Context Layer: Optional by Design

A key architectural decision was "optional external context".

Every external call has:

• timeout
• server-side try/catch fallback
• normalized response shape
• no API key leakage to frontend

Weather Normalization

Open-Meteo is normalized to a garden-focused contract:

{
  "condition": "rain",
  "is_day": true,
  "garden_effects": {
    "sky": "rain curtain",
    "particles": "rain",
    "soil": "wet",
    "light": "soft"
  }
}

Bright Data Adapter

The adapter attempts token-based Web MCP calls and degrades safely if unavailable.

const endpoint = getEndpoint(options); // token + URL
await callMcp(endpoint, "initialize", { ... });
const payload = await callMcp(endpoint, "tools/call", {
  name: "search_engine",
  arguments: { query }
});

If anything fails, fallback is returned with no user-facing crash.

Tavily Research Nudge

Used for short, evidence-oriented context:

• max two links
• no long content feed
• no fake links in fallback mode

Insight Generation: Contextual but Safe

/api/insight consumes:

• mood text
• signals
• vitality
• weather context
• public context
• research summary

OpenAI output schema:

{
  "emotional_state": "...",
  "burnout_risk": "low|medium|high",
  "garden_metaphor": "...",
  "insight": "...",
  "restoration_action": "...",
  "micro_message": "...",
  "contextual_reason": "..."
}

No medical diagnosis and no clinical claims.

UX Engineering: Calm, Not Dashboard

The app was intentionally designed with game-like emotional feedback:

• layered skies
• weather particles
• fog/heat/night transitions
• healing burst animation
• micro-message reinforcement

Demo Reliability Improvements

A simulation mode was added for consistent live demos.

Sequence:

1. Calm Morning
2. Meeting Overload
3. Doomscroll Spiral
4. Stress Event
5. Stormy Day
6. Complete Restoration
7. Recovery Mode

Interaction safety hardening:

• restoration cooldown lock
• anti-spam throttles
• simulation run lock
• disabled conflicting controls while simulation runs

Testing Strategy

Current test suite focuses on reliability-critical paths:

• energy calculation stability
• weather normalization
• Tavily fallback
• Bright Data fallback
• context response shape without keys

This gives confidence for demo + production fallback behavior.

Shipping to Cloud Run

Container pipeline:

1. Build frontend (vite build)
2. Serve static + API from Express runtime image
3. Deploy Cloud Run with env toggles

gcloud builds submit --tag gcr.io/PROJECT_ID/psychegarden

gcloud run deploy psychegarden \
  --image gcr.io/PROJECT_ID/psychegarden \
  --platform managed \
  --region asia-south1 \
  --allow-unauthenticated

What We Learned

• fallback-first architecture dramatically reduces demo risk
• optional integrations unlock advanced context without fragility
• visual metaphors can increase engagement without extra complexity
• small interaction guardrails (cooldowns/throttles) matter a lot in live demos

Where This Can Go Next

• user-specific trend timeline (local-only first)
• richer seasonal ecosystems
• personalized restoration libraries
• non-intrusive reminders and routines
• multilingual wellness reflections

PsycheGarden is a good example of balancing:

• product feel
• technical rigor
• deployability
• safe AI integration

Github Repo: https://github.com/harishkotra/psychegarden