EchoCards

EchoCards turns prompts into reusable English practice cards with explanations, saved history, and secure server-side generation.

Comment

Inspiration

English learners often receive useful answers from AI, but those answers disappear into one-time chat conversations. I wanted to build a focused tool that turns prompts, ideas, and native-language sentences into reusable English practice material that learners can save, hear, revisit, and delete explicitly.

What it does

EchoCards generates structured English practice cards instead of free-form chatbot responses.

Each lesson contains three cards by default, with a maximum of five. Each card includes:

  • learner-facing English;
  • a Traditional Chinese translation;
  • an explanation of usage;
  • optional genuine source context;
  • on-demand audio for the persisted English text.

Users unlock the app through a shared access-code gate, generate focused English-learning material, revisit saved lessons through History, request audio only for cards they want to hear, replay cached audio, and permanently delete an entire lesson through explicit confirmation.

EchoCards supports practical sentences, vocabulary, transition phrases, workplace and interview English, short dialogues, short passages, natural rewrites, and translation-to-practice. It is intentionally not a general chatbot.

How I built it

EchoCards is built with Next.js, TypeScript, React, Tailwind CSS, OpenAI, Supabase PostgreSQL, and private Supabase Storage.

The application uses:

  • server-only OpenAI text and audio providers;
  • strict structured practice-card output validation;
  • transactional lesson and card persistence;
  • signed, expiring HttpOnly access sessions;
  • durable deployment-wide text and audio quotas;
  • independent generation and audio kill switches;
  • fixed PostgreSQL RPC capabilities;
  • strict fail-closed validation of provider and database responses;
  • server-rendered History and lesson detail pages;
  • on-demand private audio with temporary signed playback URLs;
  • concurrency-safe audio admission using claims, leases, and fencing;
  • cached audio replay without another generation quota charge;
  • database-authoritative hard lesson deletion;
  • durable exact-path audio cleanup evidence.

The persisted english_text field is the sole authoritative text-to-speech input. For dialogue cards, it contains the complete speaker-labeled English dialogue rather than a summary or instruction.

How Codex and GPT-5.6 were used

EchoCards was developed through an iterative, human-supervised workflow using GPT-5.6 in ChatGPT and Codex.

I first used GPT-5.6 as a product and engineering discussion partner. Through multiple rounds of discussion, I defined the MVP scope, product boundaries, practice-card contract, persistence model, security requirements, concurrency risks, provider-cost controls, acceptance criteria, and the responsibility of each pull request.

GPT-5.6 then helped divide the project into narrowly scoped, reviewable increments. I transferred those bounded implementation prompts to Codex.

Codex acted as the repository executor. It inspected the relevant code, implemented each requested increment, added or updated tests, ran validation commands, and returned a report with code and evidence.

After each Codex task, I brought the implementation report, changed files, and test results back to GPT-5.6 for contract, security, and scope review.

I retained final authority over:

  • product scope;
  • security and authority boundaries;
  • destructive actions;
  • commits and pull requests;
  • merges;
  • database migrations;
  • provider configuration;
  • manual integration tests;
  • deployment decisions.

Examples completed through this workflow include durable text and audio quotas, private audio Storage, claim/lease/fencing behavior, cache reuse, hard lesson deletion, late-upload race handling, and correction of the dialogue spoken-content contract after a real browser test.

Challenges

The main challenge was preserving strict authority, security, and cost boundaries while keeping the product small enough for a hackathon.

Important engineering challenges included:

  • separating provider success from authoritative persisted state;
  • preventing concurrent audio requests from starting duplicate paid work;
  • keeping private Storage objects subordinate to database metadata;
  • reserving quota atomically before provider work;
  • validating all successful provider and database responses;
  • deleting a lesson while audio generation may still be in flight;
  • preserving durable cleanup evidence after database deletion;
  • keeping credentials, claim tokens, object paths, and provider settings server-controlled;
  • keeping the product focused on reusable English practice rather than general chat.

The normal in-flight late-upload deletion race is handled. A process-crash boundary after upload but before finalization or recovery remains a known limitation and would require future generalized orphan reconciliation.

Accomplishments

  • Completed the bounded prompt-to-structured-card-to-persisted-lesson flow.
  • Added strict request, provider-output, and database-response validation.
  • Added signed access-session protection.
  • Enforced durable daily text and audio quotas before paid provider calls.
  • Added server-rendered lesson History and saved lesson detail.
  • Added private on-demand audio with temporary signed playback access.
  • Added cache reuse for ready audio.
  • Added concurrency-safe audio admission and token-fenced finalization.
  • Added complete speaker-labeled dialogue audio behavior.
  • Added lesson-level hard deletion with durable exact-path cleanup evidence.
  • Closed the normal in-flight late-upload deletion race.
  • Added unit, route, component, PostgreSQL, Storage, concurrency, and guarded runtime validation.
  • Produced a complete under-three-minute product demo with voiceover.

What I learned

I learned that product boundaries matter as much as model capability. A focused practice workflow is easier to understand, validate, secure, and control than an open-ended chatbot.

I also learned that:

  • provider success is not the same as persisted authority;
  • paid AI work requires explicit admission before the provider call;
  • cached files should remain subordinate to authoritative database metadata;
  • concurrency control is also a cost-control problem;
  • destructive actions need explicit confirmation and safe repeated behavior;
  • AI coding agents work best when given narrow responsibility boundaries and testable acceptance criteria.

What's next

Potential future work includes:

  • real user accounts and per-user lesson ownership;
  • per-user Row Level Security policies;
  • background orphan reconciliation;
  • spaced repetition;
  • vocabulary folders, tags, and search;
  • learning-progress views;
  • pronunciation feedback;
  • operational monitoring;
  • English practice for learners with additional native languages.

A broader arbitrary source-to-target language product would require a separate expansion of the current card and audio-authority model.

Built With

Share this project:

Updates