A small experiment in making AI useful without making it responsible for everything.
What if planning a short walk took less effort than deciding whether to go outside?
PocketWalk is an AI-assisted walking planner that turns a few simple preferences into a structured walking plan. Choose a duration, select a difficulty, optionally enter a city, and get a practical three-step plan designed to help you spend less time planning and more time walking.
But the interesting part isn't just generating a plan with AI. It's deciding what should happen when AI returns unexpected output, a provider is unavailable, or a generated suggestion needs additional validation.
That is the engineering problem I wanted to explore.
Live app: https://pocketwalk.onrender.com
Demo video: [INSERT YOUR DEMO VIDEO URL]
Source code: [INSERT YOUR GITHUB REPOSITORY URL]
🌱 01. The Problem: Planning Shouldn't Become Another Task
Going for a walk sounds simple, but even a small decision can involve several questions:
How much time do I have?
Should I take an easy walk or something more active?
What should I do during the walk?
What if I don't know the area?
Can I get a useful suggestion without creating another account or sharing unnecessary information?
I wanted to build a small tool that reduces this friction.
PocketWalk focuses on a deliberately narrow workflow:
Input
Purpose
Duration
Plan a 10, 20, or 40-minute walk
Difficulty
Choose easy or normal
Optional city
Supply location context when available
Generated plan
Receive a structured, three-step walking experience
The product deliberately avoids accounts, persistent walking history, GPS tracking, and notifications.
The objective is not to build another giant wellness platform. It is to make one small activity easier to start.
🏗️ 02. Architecture: Where AI Fits in the System
PocketWalk uses a React and TypeScript frontend with an Express-based backend. The AI integration is designed to support a Gemma-compatible provider path, alongside a deterministic fallback.
The important architectural decision is that model output should not automatically become trusted application output.
flowchart TD
A[React + TypeScript UI] --> B[Express API]
B --> C[Request Validation]
C --> D{AI Provider Available?}
D -->|Yes| E[AI Generation]
D -->|No| F[Deterministic Fallback]
E --> G[Parse and Validate Output]
G -->|Valid| H[Structured Walk Plan]
G -->|Invalid| F
F --> H
H --> I[Display Plan to User]
This is a conceptual view of the intended flow. Confirm exact module boundaries and error paths against the current source code before treating it as a complete implementation diagram.
The responsibilities are intentionally separated
Frontend — React and TypeScript
Collects user preferences, submits requests, and presents the resulting walking plan.
Backend — Express
Handles API requests and provides a controlled boundary between the UI, external providers, and application logic.
AI integration
Generates contextual suggestions when a configured provider is available. The project supports a Gemma-compatible path, but the recorded demo does not show a live Gemma inference.
Validation and fallback
Generated output must be parsed and checked rather than accepted blindly. The fallback provides a deterministic alternative when AI generation is unavailable or unsuitable.
This separation also makes it easier to change providers without making the entire application dependent on one model.
💻 03. Engineering Detail: Treating AI Output as Untrusted
One of the most important lessons from this project is that a successful API response does not automatically mean a useful or safe application response.
An AI provider can return malformed JSON, unexpected fields, missing values, or suggestions that fail application-specific checks.
The following simplified TypeScript example illustrates the validation boundary. It is an explanatory example, not a verbatim excerpt from PocketWalk.
type WalkDifficulty = "easy" | "normal";
type WalkRequest = {
durationMinutes: 10 | 20 | 40;
difficulty: WalkDifficulty;
city?: string;
};
function validateWalkRequest(
input: unknown
): WalkRequest | null {
if (typeof input !== "object" || input === null) {
return null;
}
const value = input as Record;
const validDuration =
value.durationMinutes === 10 ||
value.durationMinutes === 20 ||
value.durationMinutes === 40;
const validDifficulty =
value.difficulty === "easy" ||
value.difficulty === "normal";
if (!validDuration || !validDifficulty) {
return null;
}
if (
value.city !== undefined &&
typeof value.city !== "string"
) {
return null;
}
return {
durationMinutes: value.durationMinutes,
difficulty: value.difficulty,
...(typeof value.city === "string"
? { city: value.city }
: {}),
};
}
Why this boundary matters
It prevents arbitrary values from entering the core planning workflow.
It makes the supported request shape explicit.
It gives the backend a predictable contract.
It allows invalid input to be rejected before expensive provider calls.
In production code, I would prefer a shared runtime schema validator for stronger type inference, precise error messages, and consistent validation across routes.
Model output needs its own validation
Request validation is only the first boundary. AI-generated output requires independent checks.
type WalkStep = {
title: string;
description: string;
};
type WalkPlan = {
steps: WalkStep[];
};
// Illustrative validation boundary.
// A real implementation must validate every field and constraint.
function validatePlanShape(
value: unknown
): value is WalkPlan {
if (typeof value !== "object" || value === null) {
return false;
}
const steps = (value as Record).steps;
return (
Array.isArray(steps) &&
steps.length === 3 &&
steps.every(
(step) =>
typeof step === "object" &&
step !== null &&
typeof (step as Record).title === "string" &&
typeof (step as Record).description === "string"
)
);
}
This checks structure, not real-world safety. Even a structurally valid plan may contain an inappropriate recommendation.
That distinction is essential: schema validation can establish that output has the expected shape; it cannot prove that a route is safe or that every recommendation is correct.
🛡️ 04. Fallbacks, Determinism, and Safety
AI availability should not be the single point of failure for a small utility.
PocketWalk includes a deterministic fallback path so the core experience can remain useful without a successful AI response.
The intended behavior can be summarized as follows:
Situation
Design response
Valid request
Continue through the planning workflow
Provider available
Attempt AI-assisted generation
Invalid generated structure
Reject it rather than trusting it
Provider unavailable
Use deterministic fallback behavior
Safety-related concern
Apply application-level checks and provide appropriate caveats
The project includes parsing, schema validation, business rules, and deterministic safety filters. These checks reduce avoidable errors, but they do not guarantee that a walking route is safe.
PocketWalk should not be presented as a live navigation or emergency-response system. Users should exercise judgment, follow local conditions, and use established navigation or emergency services when necessary.
Why I chose a fallback-first mindset
A demo that works only when a particular model is available is fragile.
A more resilient design separates the application's basic utility from the availability of its AI provider. This also makes testing easier because deterministic behavior can be exercised without depending on external model responses.
🎨 05. The User Experience: Keep the Interface Focused
PocketWalk is designed around a short interaction rather than a complicated dashboard.
The main flow is:
Choose a walk duration.
Select the desired difficulty.
Optionally provide a city.
Generate and review the plan.
Decide whether the suggested activity fits the situation.
The interface should make the next action obvious and avoid asking for information that the core experience does not require.
Suggested visual placements for the published article:
[SCREENSHOT 1 — Home screen] Show the actual deployed app and its primary controls.
[SCREENSHOT 2 — Generated plan] Show the three-step output and its readability on desktop or mobile.
[SCREENSHOT 3 — Fallback behavior] Show the real fallback experience, if it can be captured reliably.
[SCREENSHOT 4 — Responsive UI] Show the same workflow at a mobile viewport.
Use screenshots from the real application rather than stock images. A short GIF of the complete interaction would be even more useful near the beginning of the article.
🔄 06. The Request Lifecycle
The following sequence shows the logical responsibilities involved in generating a plan.
sequenceDiagram
actor User
participant UI as React UI
participant API as Express API
participant AI as AI Provider
participant V as Validation
participant F as Fallback
User->>UI: Select preferences
UI->>API: Submit walk request
API->>API: Validate request
API->>AI: Request generated plan
AI-->>API: Candidate output
API->>V: Parse and validate
alt Output passes checks
V-->>API: Validated plan
else Provider or output failure
API->>F: Create fallback plan
F-->>API: Deterministic plan
end
API-->>UI: Return plan
UI-->>User: Display result
This is a logical sequence diagram, not evidence that every branch was exercised in the recorded demo. The fallback path is part of the documented design; the demo uses fallback behavior rather than a live Gemma inference.
🧪 07. Testing and Verification
A project should be evaluated by what was tested, not just by how polished the demo looks.
The project verification snapshot recorded the following test counts:
Test suite
Recorded result
Backend tests
636
Frontend tests
151
Browser checks — suite 1
48
Browser checks — suite 2
22
Browser checks — suite 3
9
These are counts from the recorded verification artifacts, not a claim that every test represents a unique feature or that every production integration is verified.
The project also recorded build, bundle-scan, documentation-check, and audit checks. The exact status of each check should be confirmed against the latest repository state before publication.
What the test counts do not prove
Passing local tests does not automatically establish that:
A live Gemma request succeeds in production.
Live weather data is available in every environment.
Sentry events are reaching a configured external project.
A Docker image builds successfully.
GitHub Actions has completed successfully.
Every generated walking suggestion is safe.
The recorded demo does not demonstrate live Gemma inference, live weather verification, Sentry ingestion, a Docker build, or a GitHub Actions run.
I would rather state those limitations clearly than imply that unverified integrations work.
🚀 08. Deployment
PocketWalk is deployed at:
https://pocketwalk.onrender.com
The recorded deployment check confirmed that the application was reachable and that the root page returned HTTP 200.
The documented production configuration uses the deterministic AI fallback (GEMMA_PROVIDER=none), the Open-Meteo weather provider configuration, and disabled Sentry reporting. A configured weather provider is not, by itself, proof that every live weather request succeeds.
This deployment was useful for validating the real application entry point, but it should not be confused with verification of every optional integration.
🧠 09. Why This Is an Open Innovation Project
I wanted PocketWalk to explore a broader engineering principle: AI should be an optional capability that improves a useful product, not a dependency that makes the product unusable without it.
That principle influences several design choices:
Provider flexibility: avoid coupling the entire application to one model.
Deterministic behavior: retain a useful fallback when generation is unavailable.
Explicit validation: separate model output from trusted application data.
Minimal data collection: avoid accounts, persistent history, and unnecessary tracking.
Honest evaluation: distinguish local tests, deployed behavior, and integrations that remain unverified.
These decisions make the project easier to reason about and give future contributors clearer places to improve it.
📚 10. What I Learned
Building PocketWalk reinforced several lessons for me as a student developer.
AI integration is more than calling an API.
Parsing, validation, failure handling, and predictable behavior are part of the feature.A fallback is a product decision.
It protects the basic experience from depending entirely on an external service.Tests and deployment evidence answer different questions.
A passing test suite, a successful build, and a reachable deployment are separate forms of evidence.Safety claims need boundaries.
Validation can reject known invalid patterns, but it cannot certify that a route is safe in the real world.Scope matters.
A small tool with a clear purpose can be a better learning project than a much larger application with many disconnected features.
🔭 11. What I Would Improve Next
The next steps should be driven by verified gaps rather than adding features for their own sake.
Add a repeatable integration test for a real Gemma-compatible provider.
Verify live weather behavior with both successful responses and provider failures.
Confirm external Sentry event ingestion with an intentional, safe test event.
Run and record a reproducible Docker build.
Verify the complete GitHub Actions workflow from a clean commit.
Improve accessibility, mobile interaction, and error-state feedback.
Document the limits of generated suggestions and the fallback behavior.
Each item should be marked complete only after there is reproducible evidence.
🌍 12. Closing
PocketWalk started with a simple question: can an AI-assisted tool make going for a walk easier without making the experience unnecessarily complicated?
The result is a small walking planner built around a focused UI, a backend API, AI-assisted generation, validation, and deterministic fallback behavior.
It is not a certified navigation system, and the recorded demo does not prove every optional integration works live. Those boundaries are part of the project story, too.
For me, the most valuable takeaway is that building with AI means designing for the moments when AI is unavailable, incorrect, or simply not needed.
Sometimes the best AI product is the one that knows when not to depend on AI.
Project links
Live application: https://pocketwalk.onrender.com
Demo video: https://youtu.be/wruSn74VnNU
GitHub repository: https://github.com/piyusshhjangid/PocketWalk
Challenge: https://dev.to/challenges/hacktoberfest-week1-2026-10-05
Top comments (0)