Parlons

Parlons turns French grammar into real conversation through focused practice, GPT-5.6 role-play, personalized corrections, and review plans for English-speaking A1–A2 learners.

Comment

Inspiration

Many French learners know more grammar than they can actually use. They may understand articles, verb conjugations, or question forms in an exercise, but hesitate when ordering coffee, asking for directions, attending class, or introducing themselves.

I wanted to close that gap between knowing a rule and using it naturally.

That idea became Parlons: an AI-powered learning experience for English-speaking A1–A2 learners. Instead of treating grammar and conversation as separate activities, Parlons connects them through one continuous loop:

Learn → Practice → Converse → Correct → Review

What Parlons does

Parlons contains 24 lessons organized into five gradual stages, progressing from introductions and sentence foundations to practical travel, education, work, and integrated A2 scenarios.

Each lesson helps learners:

  1. Study one focused grammar concept.
  2. Review useful vocabulary and examples.
  3. Complete short, deterministic exercises.
  4. Write an open response without being restricted to one exact answer.
  5. Use the concept in a realistic French conversation.
  6. Receive one focused correction with a concise English explanation.
  7. Add recurring mistakes to a personalized review plan.

Scenarios include ordering at a café, navigating a city, checking into a hotel, attending university, handling travel disruptions, and interviewing for a job.

Learners can begin immediately as guests. Optional local accounts store completed lessons, objective practice results, session history, and review priorities in SQLite.

How I built it

Parlons uses a deliberately lightweight architecture:

  • Node.js 20
  • Browser-native HTML, CSS, and JavaScript
  • SQLite with better-sqlite3
  • OpenAI Responses API with GPT-5.6
  • JSON and JSONL curriculum authoring
  • Node’s built-in test runner and cryptography

The browser loads curriculum summaries and complete lessons from a Node API. The server validates and imports the committed curriculum into SQLite transactionally, then uses the same database for user accounts, sessions, progress, and source traceability.

When AI mode is enabled, GPT-5.6 receives the selected lesson, CEFR level, grammar focus, scenario, success criteria, recent conversation, and learner’s latest message. It returns structured JSON containing:

  • An in-character French reply
  • An optional focused correction
  • A short English explanation
  • A reusable skill category
  • A progress update
  • A scenario-completion signal

The server validates this structure before anything is displayed or saved. Without an API key, Parlons provides a deterministic scenario-aware fallback so judges can still test the complete workflow.

How Codex accelerated the project

Codex supported the majority of the engineering workflow.

It helped inventory a mixed French-learning archive containing Markdown, DOCX, PPTX, PDF, legacy DOC, and image files. Together, we built a deterministic extraction and classification pipeline that catalogued 98 sources and recovered 14,847 private text segments from 88 readable files.

Codex also helped:

  • Design the five-stage curriculum structure
  • Create and validate 24 original lessons
  • Implement SQLite migrations and repositories
  • Build authentication and persistent progress
  • Connect curriculum and tutor APIs
  • Develop the responsive browser interface
  • Write tests before implementing important behavior
  • Diagnose extraction collisions and tutor fallback bugs
  • Verify desktop and mobile learning flows
  • Conduct final code, dependency, privacy, and security reviews

The key product decisions remained human decisions: the target audience, curriculum progression, learning loop, correction limits, privacy boundary, minimal-dependency architecture, and the choice not to falsely grade personal production as an exact-match exercise.

Challenges

The first major challenge was using existing learning material responsibly. The archive included personal notes and potentially third-party course resources. Copying that wording into a public submission would create privacy, copyright, and quality risks.

Parlons therefore treats the archive only as private research input. Extracted passages are excluded from Git and never served by the website. The committed catalog contains metadata, hashes, language hints, and broad topic tags, while every published explanation, example, exercise, and scenario was newly written for Parlons.

Another challenge was evaluating open-ended answers. Exact-string grading works for constrained exercises but fails when a learner gives a valid personal answer—for example, stating an age not included in a predefined list. Parlons now presents open production as a self-check and excludes it from machine-graded accuracy. Adaptive correction happens during conversation, where GPT-5.6 can interpret the answer in context.

Security also required careful boundaries. API keys remain server-side, passwords are hashed with scrypt, session tokens are stored only as hashes, SQL values use prepared statements, and learner/model messages are escaped before rendering.

What I learned

The most important lesson was that generative AI works best when surrounded by deterministic structure.

GPT-5.6 provides flexible, contextual conversation and correction, while the curriculum, prerequisites, accounts, progress calculations, and review ranking remain predictable and testable. Structured model output connects these two worlds: a natural-language correction becomes reliable learning data that can support future practice.

I also learned that content provenance and safety should be architectural decisions, not final submission checks. By separating private source material from original publishable lessons, Parlons can remain useful, reviewable, and suitable for a public repository.

What’s next

The next steps are to add teacher-reviewed correction evaluations, audio and pronunciation practice, stronger controls for a public live-AI deployment, account deletion and retention tools, and learner testing with a broader English-speaking audience.

Parlons began with a simple goal: help learners stop leaving French grammar inside the textbook—and start using it in conversation.

Built With

Share this project:

Updates