Forem: Adam Pitera

I Built Surveys That Get Smarter With Every Response

Adam Pitera — Fri, 13 Mar 2026 13:47:09 +0000

Using Google Gemini to generate follow-up questions based on what each person says — and what's missing from the dataset.

I wrote about the concept behind Dyadem when I built it for the Gemini 3 Hackathon. Since then I've iterated on it — added an AI question authoring step, deployed it for a real community questionnaire, and learned a lot about what works. This article goes into the engineering.

Most surveys ask everyone the same questions. You get shallow data and bored respondents.

I built Dyadem — an open-source survey platform where AI generates follow-up questions for each respondent based on two things: what they just said, and what gaps exist across all responses so far. Early respondents get broad exploratory questions. By response 50, the AI is asking about specific things nobody's mentioned yet.

Here's how it works and what I learned.

The Flow

User answers 3 fixed questions
  → App gathers dataset context (aggregate stats, themes, gaps)
  → Builds a prompt: this person's answers + what everyone else said
  → Gemini generates 1-2 follow-up questions
  → User answers them
  → Everything submitted together

Stack: Next.js 14.2, TypeScript, PostgreSQL (Neon), Drizzle ORM, Google Gemini.

The Prompt That Makes It Work

This is the bit I found most interesting to design. The prompt gives Gemini two types of context: what the individual said, and a statistical picture of the whole dataset.

You are designing follow-up questions for an anonymous survey.

This person just answered:
- Biggest financial pressure: {{biggest_pressure}}
- How things have changed (1=much better, 5=much worse): {{change_direction}}
- What they've sacrificed: "{{sacrifice}}"

Current dataset ({{total_responses}} responses so far):
- Top pressure: {{top_pressure}} ({{top_pressure_pct}}%)
- Average change score: {{avg_change}}/5
- Most common sacrifice themes: {{sacrifice_themes}}
{{emerging_gap_line}}

Generate 1-2 follow-up questions that:
1. DIG DEEPER into this person's specific situation
2. FILL GAPS — ask about something the community hasn't covered yet
3. Are QUICK to answer (choice, scale, or short text)
4. Feel CONVERSATIONAL, not clinical
5. NEVER ask for identifying information

{{volume_guidance}}

The {{volume_guidance}} bit shifts the AI's strategy based on how much data exists:

if (context.totalResponses < 10) {
  volumeGuidance = "We have very few responses. Ask broader questions "
    + "to establish baseline understanding.";
} else if (context.totalResponses < 50) {
  volumeGuidance = "We're building a picture. Start probing for "
    + "nuance within the dominant themes.";
} else {
  volumeGuidance = "We have substantial data. Ask targeted questions "
    + "to uncover the most surprising or underreported patterns.";
}

This means the survey changes character as it collects data. The first few people get "tell us about you" questions. Later respondents get "nobody's mentioned X yet — what's your experience?" It's a small amount of logic that makes a big difference to data quality.

Getting Structured Output From an LLM

The other problem worth solving: Gemini returns text, but I need a question object I can render in React. Zod + Gemini's structured output mode handles this.

Define what a valid question looks like:

export const adaptiveQuestionSchema = z.object({
  questions: z.array(
    z.object({
      question_text: z.string(),
      input_type: z.enum(["single_choice", "scale", "short_text"]),
      options: z.array(z.string()).optional(),
      scale_min_label: z.string().optional(),
      scale_max_label: z.string().optional(),
      reasoning: z.string(),
    })
  ).min(1).max(2),
});

Pass that schema directly to Gemini:

const response = await getAI().models.generateContent({
  model: MODELS.flash,
  contents: prompt,
  config: {
    responseMimeType: "application/json",
    responseJsonSchema: zodToJsonSchema(adaptiveQuestionSchema),
  },
});

No parsing. No regex. No "please return JSON" in the prompt and hoping for the best. The model is constrained at the API level to return exactly this shape.

The reasoning field is worth calling out — it forces the model to explain why it chose each question. This works like chain-of-thought prompting but baked into the output schema. It improves question quality and gives you something to debug with.

Cost: Cheaper Than You'd Think

I used three different Gemini models matched to the task:

Task	Model	Cost per call
Content moderation	Flash Lite	~$0.0005
Adaptive questions	Flash	~$0.001–0.003
Theme extraction & reports	Pro	~$0.01–0.03

Total per survey submission: about $0.002–0.004. Cheap enough for a community project with no budget.

If the AI Breaks, the Survey Still Works

One design rule I'd push for any AI-enhanced feature: the AI should improve the experience, never block it.

try {
  const res = await fetch(`/api/s/${slug}/adaptive-questions`, {
    method: "POST",
    body: JSON.stringify(answers),
  });
  if (res.ok) {
    const data = await res.json();
    if (data.questions?.length > 0) {
      setAdaptiveQuestions(data);
      setStage("adaptive");
      return;
    }
  }
} catch {
  // AI failed — skip to submission
}
doSubmit(answers, null);

If Gemini is down or slow, people still submit their survey. You lose the follow-ups, not the whole product.

Next Steps

Response quality scoring. Use the AI to score how substantive each free-text answer is. Vague responses get a gentler follow-up encouraging more detail. Detailed answers get acknowledged and move on. Adaptive effort, not just adaptive questions.

Live gap visualisation. A real-time dashboard showing survey creators which topics are well-covered and which have gaps as responses come in — with the ability to manually nudge the AI's priorities. "Stop asking about rent. Start asking about childcare."

Respondent clustering. After enough responses, identify respondent archetypes and tailor the follow-up strategy per cluster, not just per individual answer.

Research-grade export. Structured export that preserves the adaptive question context — not just a CSV. A researcher needs to know why each person got different follow-ups to interpret the data properly.

Takeaways

Give the AI more than just the current input. The follow-up questions are good because Gemini sees the individual's answers and the aggregate dataset. Without that broader context, you just get generic follow-ups.

Constrain output with schemas, not prompts. Asking an LLM to "please return JSON" is fragile. Gemini's responseJsonSchema with Zod validation is reliable.

Volume-aware prompting matters. Shifting the AI's behaviour based on how much data exists is a small detail that changes the character of the whole system.

Dyadem is open source — GitHub repo here if you want to look at the full implementation.

I Built an Adaptive AI Feedback Platform with Gemini 3 in a Weekend

Adam Pitera — Mon, 09 Feb 2026 18:16:22 +0000

What if a questionnaire could learn what to ask? I built Dyadem for the Gemini 3 Hackathon to find out.

Questionnaires are notoriously tricky to develop. Community outreach relies heavily on focus groups because simple surveys often miss the point. There's a constant trade-off between long, exhaustive question lists and brief, open-ended ones that generate data nobody can use.

But what if AI could learn what to ask?

I built Dyadem for the Gemini 3 Hackathon — an anonymous feedback platform where the questions adapt based on what the community has already said. The example I deployed is a cost-of-living survey, and it's live at dyadem.dev.

How the feedback loop works

A short set of fixed questions frames the survey and establishes a baseline — including a free-text element where people describe what they've had to give up. Gemini takes these answers and generates completely novel, tailored follow-up questions for that specific person.

That completes the submission. But behind the scenes, Gemini is also extracting themes from all submissions. Those themes feed back into the question generation prompt, so the next person gets smarter, more targeted follow-ups.

The loop keeps running. The more people contribute, the better the questions get.

The final output is a separate Gemini call on a higher thinking level, tasked with producing a narrative insight across the whole dataset — weaving together the statistics, the themes, and the human stories. When new submissions arrive, the insight regenerates. Any shifts in the data are reflected in the narrative.

The adaptive question prompt

The core of the system is the prompt that generates follow-up questions. It receives both the individual's answers and a summary of the entire dataset:

You are designing follow-up questions for an anonymous survey.

This person just answered:
- Biggest financial pressure: {{biggest_pressure}}
- How things have changed (1-5): {{change_direction}}
- What they've sacrificed: "{{sacrifice}}"

Dataset overview ({{total_responses}} responses so far):
- Top pressure: {{top_pressure}} ({{top_pressure_pct}}%)
- Most common sacrifice themes: {{sacrifice_themes}}
{{emerging_gap_line}}

Generate 1-2 follow-up questions that:
1. DIG DEEPER into this person's specific situation
2. FILL GAPS in the dataset
3. Are QUICK to answer
4. Feel CONVERSATIONAL, not clinical
5. NEVER ask for identifying information

The key line is {{emerging_gap_line}} — if the system detects a category with very few responses, it tells Gemini about the gap. So if only two people have mentioned childcare, the next person who selects something related might get: "You're one of the few to mention this — what would help most?"

The questions come back as structured JSON validated with Zod, so the frontend can render them dynamically:

// Simplified — three question types the AI can generate
type AdaptiveQuestion =
  | { type: "choice"; label: string; options: { value: string; label: string }[] }
  | { type: "scale"; label: string; min: number; max: number }
  | { type: "text"; label: string; placeholder: string };

The emergence

With 5 submissions, the follow-up questions are broad. With 50, Gemini starts probing the dominant themes. With 200, it could find contradictions and underreported experiences. Nobody programmes these later questions — they would emerge from the data.

My background is in psychology and intelligent systems, so I'm drawn to the problem of how you actually listen to a community at scale. Traditional surveys ask everyone the same thing regardless of context. Dyadem tries to do what a good interviewer does — respond to what someone has said, probe where it matters, and synthesise many voices into a collective insight.

What I'd do differently

For all the technology, the most popular survey tools have proven over time to be the simplest to deploy. Google Forms is ubiquitous precisely because the question-maker gets a nicely populated spreadsheet they can see and analyse however they want.

There are lessons in that. Ideally, Dyadem would have a much simpler deployment — no VPS required, just clone and run. And alongside the AI-generated narrative, the survey creator needs to see the raw data too. That means the output would need to be regularised somehow when the AI introduces new topics through adaptive questions — otherwise you end up with a spreadsheet where every row has different columns.

That tension between AI flexibility and structured data output is, I think, the interesting design problem for anyone building adaptive survey tools.

Next.js Server Components: From 226ms to 23ms in Production

Adam Pitera — Wed, 23 Jul 2025 18:34:55 +0000

A practical migration guide for moving Next.js applications from client-side data fetching to server components with caching.

Quick Start

Find a page using useEffect for data fetching
Remove "use client"
Make component async
Wrap fetch in unstable_cache
Test with DevTools (look for cache headers)

Details below, or jump to Real Example.

The Problem

Most Next.js apps default to client-side data fetching:

"use client";

export default function DashboardPage() {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetch('/api/dashboard')  // Runs on every page visit - no caching!
      .then(res => res.json())
      .then(setData)
      .finally(() => setLoading(false));
  }, []);

  if (loading) return <LoadingSpinner />;
  return <Dashboard data={data} />;
}

Issues: No caching, loading spinners everywhere, large JavaScript bundles, poor SEO.

The Solution

Server components with caching:

import { unstable_cache } from 'next/cache';

const getCachedDashboard = unstable_cache(
  async () => {
    const res = await fetch('/api/dashboard');  // Cached for 60s - subsequent visits are instant!
    return res.json();
  },
  ['dashboard'],
  { revalidate: 60 }
);

export default async function DashboardPage() {
  const data = await getCachedDashboard();
  return <Dashboard data={data} />;
}

Results: First load 226ms → cached loads 23-38ms (83% faster), no loading states, smaller bundles.

Note: unstable_cache API may change in future Next.js releases. Monitor release notes when upgrading.

Migration Strategy

When to Use Each Type

Component Decision Tree:
├─ Uses onClick/onChange? → Client Component
├─ Uses browser APIs? → Client Component  
├─ Needs useState/useEffect? → Client Component
├─ Real-time updates? → Client Component
├─ Only displays data? → Server Component
└─ Fetches data? → Server Component + Cache

Migration Steps

Remove "use client" directive
Convert to async function
Move data fetching into component
Add caching with appropriate duration
Extract interactive elements to client components

Real Example

// Before: Everything in one client component
"use client";
function ProductPage({ id }) {
  const [product, setProduct] = useState(null);
  const [quantity, setQuantity] = useState(1);

  useEffect(() => {
    fetchProduct(id).then(setProduct);  // Fetches on every visit - no caching!
  }, [id]);

  return (
    <div>
      <h1>{product?.name}</h1>
      <p>${product?.price}</p>
      <input 
        type="number" 
        value={quantity} 
        onChange={(e) => setQuantity(e.target.value)}
      />
      <button onClick={() => addToCart(id, quantity)}>
        Add to Cart
      </button>
    </div>
  );
}

// After: Server component with client island
// app/product/[id]/page.tsx
const getCachedProduct = unstable_cache(
  (id) => fetchProduct(id),  // Cached for 5 minutes - fast repeat visits!
  (id) => ['product', id],
  { revalidate: 300 }
);

export default async function ProductPage({ params }) {
  const product = await getCachedProduct(params.id);

  return (
    <div>
      <h1>{product.name}</h1>
      <p>${product.price}</p>
      <AddToCartForm productId={params.id} />  {/* Only this part needs client */}
    </div>
  );
}

// components/add-to-cart-form.tsx
"use client";
export function AddToCartForm({ productId }) {
  const [quantity, setQuantity] = useState(1);

  return (
    <>
      <input 
        type="number" 
        value={quantity} 
        onChange={(e) => setQuantity(e.target.value)}
      />
      <button onClick={() => addToCart(productId, quantity)}>
        Add to Cart
      </button>
    </>
  );
}

Common Patterns

Dashboard with Charts

export default async function Dashboard() {
  const stats = await getCachedStats();

  return (
    <>
      <StatsGrid data={stats} />    {/* Server: displays data */}
      <InteractiveChart />          {/* Client: user can interact */}
    </>
  );
}

Form Pages

export default function ContactPage() {
  return (
    <>
      <PageHeader />      {/* Server: static content */}
      <ContactForm />     {/* Client: handles submission */}
      <Footer />          {/* Server: static content */}
    </>
  );
}

Cache Invalidation

import { revalidateTag } from 'next/cache';

export async function updateData(formData) {
  await saveToDatabase(formData);
  revalidateTag('dashboard');  // Clear cache
}

Error Handling

export default async function Page() {
  try {
    const data = await getCachedData();
    return <DataDisplay data={data} />;
  } catch (error) {
    return <ErrorMessage />;  // No error boundaries needed
  }
}

Cache Duration Guide

Content Type	Cache Duration	Example Use Case
User dashboard	30-60s	Recent activity
Product catalog	5-60min	Inventory updates
Blog posts	Hours/days	Rarely changes
User-specific	0-30s	Personal data

Common Pitfalls

1. Functions Don't Serialize

// ❌ Functions can't pass from server to client
const config = {
  validate: (val) => val > 0
};

// ✅ Pass data instead
const config = {
  minValue: 0
};

Rule: If JSON.stringify() can't handle it, neither can server components.

2. Don't Over-Split

// ❌ Too many tiny components
<ServerWrapper>
  <ServerTitle />
  <ServerPrice />
  <ClientButton />
</ServerWrapper>

// ✅ Logical grouping
<ProductCard>           {/* Server: all static parts */}
  <AddToCartButton />   {/* Client: just the button */}
</ProductCard>

Rule: Extract client components only for event handlers or hooks.

3. Forms Need Client

// ❌ Server components can't handle events
export default async function Form() {
  return <form onSubmit={handleSubmit}>...

// ✅ Forms are always client components
"use client";
export default function Form() {
  return <form onSubmit={handleSubmit}>...

Rule: If users can type or click, it's a client component.

Verification

Test your cache is working:

async function testCache(url) {
  for (let i = 0; i < 3; i++) {
    const start = Date.now();
    const res = await fetch(url);
    console.log(`Request ${i + 1}: ${Date.now() - start}ms - ${res.headers.get('x-nextjs-cache') || 'MISS'}`);
    await new Promise(r => setTimeout(r, 1000));
  }
}

Expected: First ~200ms (MISS), then ~30ms (HIT).

Production Tips

API Stability

Pin Next.js version: "next": "14.2.3" (no ^)
Check release notes before upgrading
Test in staging first

Edge Runtime

Check database driver compatibility
No file system access
Some packages won't work

Performance Expectations

Results vary based on infrastructure and data source latency. Typical improvement: 50-90% for cached requests.

Summary

Use server components for:

Data displays and dashboards
Content that changes infrequently
Reducing bundle size

Keep client components for:

Forms and user input
Real-time features
Browser APIs

Start with one data-heavy page, measure the improvement, then expand.

Resources

Why I Deploy to Railway Using GitHub Container Registry Instead of Native Builds

Adam Pitera — Fri, 18 Jul 2025 16:30:18 +0000

TL;DR: Railway's build cache permanently misdetected my Next.js app as Deno, forcing me to delete the entire project. Now I build Docker images locally and deploy via GitHub Container Registry for full control over the build process.

After spending an entire day debugging Railway's build system, I discovered why Docker with GitHub Container Registry (GHCR) can be a better choice than platform-native builds. Here's what I learned and how you can avoid my mistakes.

The Problem That Started Everything

My Next.js app refused to build on Railway. The platform had detected my project as "Deno" (due to a stray test file) and cached this decision permanently. Even after:

Removing all Deno files from my repository
Adding proper Node.js configuration files
Manually deleting Deno from Railway's dashboard (Build > Providers section)
Multiple redeploys and cache clears

Railway continued trying to build with Deno. The platform was building phantom files that no longer existed, completely ignoring my current repository state.

The only fix? Delete the entire Railway project and start over.

This experience taught me that "build once, deploy anywhere" with containers beats platform-specific auto-detection when things go wrong.

The GHCR Solution

Instead of relying on Railway's auto-detection, I now build Docker images locally and deploy them via GitHub Container Registry. Here's how:

Prerequisites

Configure Next.js for standalone output in next.config.js:

module.exports = {
  output: 'standalone',  // Essential - creates the server.js file
  // ... your other config
}

2. Set up GitHub authentication (one-time)

# Create a personal access token at github.com/settings/tokens
# with 'write:packages' permission

# Login to GitHub Container Registry
echo $GITHUB_TOKEN | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin

1. Create your Dockerfile

FROM node:18-alpine AS builder
WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci

# Build application
COPY . .
RUN npm run build

# Production stage
FROM node:18-alpine
WORKDIR /app

ENV NODE_ENV=production
ENV PORT=3000

# Copy built application
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public

EXPOSE 3000
CMD ["node", "server.js"]

2. Build and push to GHCR

# Build your image
docker build -t myapp:latest .

# Tag for GHCR
docker tag myapp:latest ghcr.io/YOUR_GITHUB_USERNAME/myapp:latest

# Push to registry
docker push ghcr.io/YOUR_GITHUB_USERNAME/myapp:latest

3. Configure Railway

Create railway.toml in your repository:

[deploy]
image = "ghcr.io/YOUR_GITHUB_USERNAME/myapp:latest"

Railway now deploys your pre-built image instead of building from source.

Why This Approach Works Better

Control: You define the build process, not the platform. What works locally works in production.

Portability: Your Docker image deploys anywhere—Railway today, AWS tomorrow. No vendor lock-in.

Debugging: Test the exact production image locally with docker run -p 3000:3000 myapp:latest. Build errors surface immediately on your machine.

Predictability: No cached detection states or mystery failures. Docker builds are explicit and reproducible.

Quick Comparison

Railway Native Builds	Docker + GHCR
Instant setup	Requires Docker setup
Platform controls build	You control everything
Limited debugging	Test locally first
Railway-only	Deploy anywhere

When to Use Each Approach

Railway native builds: Best for standard apps with clean project structures, prototypes, and when you trust the auto-detection to work correctly.

Docker + GHCR: Choose this when you need explicit build control, have hit detection issues, or prefer testing exact production images locally.

The Verdict

Railway's native builds optimise for the happy path—when they work, they're delightfully simple. But when detection goes wrong or you need specific configurations, the magic becomes a liability.

After my debugging marathon, I've learned to value explicit over implicit, control over convenience. Docker with GHCR gives you that control while still deploying to Railway's excellent infrastructure. Your mileage may vary, but for me, the peace of mind is worth the extra setup.

Getting Started

If you're experiencing Railway build issues or want more deployment control:

Start with the Dockerfile above
Adjust for your framework's requirements
Test locally before pushing to GHCR
Enjoy predictable deployments

The extra setup time pays off in deployment confidence and debugging capability.

Useful Resources

Have you switched from platform builds to Docker? What drove your decision? Let me know in the comments.

Why I Ditched API Routes for Server Actions in Next.js

Adam Pitera — Tue, 08 Jul 2025 20:11:51 +0000

I just deleted 128 lines of code and my app works better. Here's how Server Actions transformed my secure form handling in Next.js.
My first attempt used a traditional API route with 173 lines of HTTP boilerplate. Server Actions promised to handle the HTTP layer automatically - and they delivered, eliminating 128 lines while keeping the same security features.

The Problem: So Much Boilerplate

My form needed CSRF protection, rate limiting, and complex validation. The traditional API route approach worked, but required extensive manual HTTP handling:

// app/api/submit-form/route.ts - 173 lines
export async function POST(request: NextRequest) {
  // Before: So much manual work!
  const formData = await request.formData();  // Manual parsing

  // Manual extraction
  const token = request.cookies.get("csrf_token")?.value; 

  if (!token) {
    return NextResponse.json(
      { error: "Missing token" }, 
      { status: 403 }
    ); // Manual responses
  }

  // ... 165 more lines of HTTP plumbing
}

The Solution: Server Actions

Server Actions let me call server functions directly from React components:

// app/actions.ts - 45 lines
"use server";

export async function submitForm(formData: FormData) {   
  const store = await cookies();
  const token = store.get("csrf_token")?.value;

  if (!token) 
    return { error: "Missing token", success: false };

  const result = await database.insert(data);
  return { success: true };
}

What I Eliminated

128 lines of code (73% reduction!)
HTTP status code management
Manual request/response handling
Method checking (GET/POST/PUT/DELETE)
JSON parsing/serialisation

What Stayed the Same

Security (CSRF, rate limiting, validation)
Database operations
Anonymous data handling

My code now has the same security with less complexity.

The Result

The real win? Everything is just JavaScript now. No context switching between "client thinking" and "API thinking". My validation schema lives in one place and works on both client and server. When debugging, the error is right there in my component instead of buried in server logs.

Key Takeaways

Server Actions handle HTTP automatically
Security logic stays server-side
Less code complexity

When NOT to Use Server Actions

While Server Actions simplified my use case, they're not always the right choice:

Building a public API
Need custom HTTP headers or status codes
Most webhook endpoints
Response streaming

If you're building an API for mobile apps or need fine-grained HTTP control, stick with traditional API routes.

Conclusion

Server Actions excel at form handling - especially when security matters. All validation logic stays server-side, hidden from prying eyes. Your implementation details will vary, but the core benefit remains: less boilerplate, same security.

Have you migrated to Server Actions? What was your experience? Drop a comment below!