Hoc hoa THCS

Hoa hoc THCS — a mobile-first web app that helps Vietnamese lower-secondary students (grades 8–9) master Chemistry through interactive theory cards, four quiz types , XP/streak progression.

Comment

Hoá học THCS nâng cao

Inspiration

Two weeks before this project began, I was not a developer. I was simply a parent looking for a better way to help my son learn lower-secondary Chemistry in Vietnam.

Chemistry in grades 8–9, especially the gifted-student or HSG track, can quickly become overwhelming. Students must understand reaction chains, balance equations, connect acids, bases, salts, metals, and oxides, and move between inorganic and organic Chemistry. Most practice still happens with a textbook and a notebook.

I wanted to give my son a more structured learning loop: short lessons, focused practice, immediate explanations, mistake review, and realistic mock exams. Inspired by the habit-forming experience of language-learning applications, I started building Hoá học THCS nâng cao, even though I had no previous coding experience.

With Codex and GPT-5.6 as my AI engineering partners, that idea became a working MVP in approximately two weeks.

What it does

Hoá học THCS nâng cao is a mobile-first Progressive Web App designed around the Vietnamese grades 8–9 Chemistry curriculum.

Students can:

  • Follow a structured learning path across inorganic and organic Chemistry.
  • Study theory through short, focused lesson cards.
  • Practice with single-choice, multiple-choice, fill-in-the-blank, and equation-balancing questions.
  • Receive immediate grading and explanations.
  • Revisit incorrectly answered questions through a dedicated review loop.
  • Track XP, streaks, stars, and lesson progress.
  • Take configurable timed mock exams.
  • Install the application as a PWA and continue studying offline.
  • Keep progress locally without creating an account.
  • Optionally sign in and synchronize progress across devices through Supabase.

Equation balancing is graded numerically rather than through simple string matching. For a reaction written as

$$ aA + bB \rightarrow cC + dD, $$

the application validates the coefficient vector

$$ (a,b,c,d) $$

and accepts equivalent proportional answers only when they represent the same balanced equation.

How we built it

The application uses:

  • React 18 and TypeScript
  • Vite and Tailwind CSS
  • Zustand persistence for local-first progress
  • Supabase for optional authentication and cross-device synchronization
  • Workbox and vite-plugin-pwa for installation and offline support
  • Vitest and Testing Library for unit and component tests
  • Playwright for desktop, mobile, production-build, and offline PWA testing
  • GitHub Pages for static hosting

However, the most important part of the build was not only the technology stack. It was the AI-assisted engineering workflow.

I defined the product need and remained the final decision-maker. Claude Code acted as the architect, converting requirements into scoped plans, acceptance criteria, and risk classifications. Codex running GPT-5.6 acted as the engineering engine, exploring the repository, implementing features, fixing defects, writing tests, and running validation. Fresh Codex or Gemini executions independently reviewed higher-risk changes.

The workflow follows this structure:

  1. Define the user need and expected outcome.
  2. Create an approved, risk-tiered implementation plan.
  3. Delegate implementation and validation to Codex with GPT-5.6.
  4. Produce a snapshot-bound engineering handoff.
  5. Run independent verification appropriate to the risk tier.
  6. Return findings through a remediation loop.
  7. Let the human make the final release decision.

To control token usage, planning and implementation run in separate sessions. Agents receive only the context required for their role. Successful validation is recorded once for an exact implementation snapshot instead of being rerun by every agent. One structured handoff transfers scope, commit information, commands, results, deviations, and review findings between sessions.

Challenges we ran into

Building without a coding background

The first challenge was learning that asking an AI to “build an application” is not enough. Requirements must still be bounded, architecture decisions must be explicit, and every feature needs measurable acceptance criteria. Otherwise, agents can produce working code that does not solve the intended problem.

Controlling AI context and token usage

Our initial workflow accumulated too much context. Multiple instruction documents repeated similar rules, long sessions carried unnecessary history, and different agents sometimes repeated the same validation.

We redesigned the workflow around clear ownership and three risk tiers: NORMAL, ELEVATED, and CRITICAL. Low-risk interface work no longer receives the same expensive review process as authentication, security, deployment, or architecture changes.

We also stopped rerunning successful gates merely to reproduce logs. Validation now runs once for each unchanged implementation snapshot, and its evidence is passed through the handoff.

Establishing trust between agents

A statement such as “all tests passed” is not sufficient release evidence. Results must be tied to the exact code that produced them.

Each handoff therefore records the candidate commit, dirty-worktree fingerprint when applicable, commands, exit statuses, timestamps, tool versions, deviations, and review findings. A fresh reviewer can inspect the same candidate without inheriting the implementation agent’s reasoning.

Implementing real Chemistry grading

Chemical-equation balancing is a numeracy problem, not a text-comparison problem. The grading logic must handle coefficients, equivalent proportions, omitted coefficient 1, malformed answers, and conservation of each chemical element.

Making static hosting behave like an application

GitHub Pages hosts the project under /Hoa_hoc_THCS/, which created challenges for SPA routing, Supabase authentication redirects, service-worker scope, and offline caching.

These required explicit redirect allowlists, a generated 404.html fallback, base-path testing, and dedicated PWA tests.

Keeping dependencies secure

A routine dependency upgrade became more complex when new advisories appeared after the original plan had been approved.

Instead of silently expanding the scope, we amended the plan, reassessed the risk, reran the applicable gates, and independently reviewed the security-sensitive changes.

The remediation reduced seven known vulnerabilities, including one critical vulnerability, to zero and added automated vulnerability and license-policy checks.

Accomplishments that we're proud of

  • Built a complete mobile-first Chemistry learning MVP in approximately two weeks.
  • Implemented lessons, four practice formats, equation-balancing validation, progression tracking, mistake review, and timed mock exams.
  • Added local-first progress so students can begin without creating an account.
  • Added optional Supabase synchronization across devices.
  • Made the application installable and usable offline as a PWA.
  • Created a documented multi-agent engineering workflow instead of relying on unstructured prompting.
  • Reduced unnecessary token consumption by separating responsibilities and avoiding duplicated validation.
  • Introduced risk-tiered independent review for higher-risk changes.
  • Reduced known dependency vulnerabilities from seven to zero.
  • Used a fresh Codex/GPT-5.6 execution as an adversarial reviewer, which found real defects in previously generated security code.

What we learned

The most important lesson was that AI does not remove the need for an engineering process. It makes a disciplined process even more important.

We learned that more context does not automatically produce better results. A bounded plan, relevant files, explicit acceptance criteria, and a reliable handoff are more effective than giving every agent the complete project history.

Token optimization should remove duplicated work, not quality controls. We reduced unnecessary context by separating agent responsibilities, ending long interactive sessions, avoiding repeated repository reviews, and reusing snapshot-bound validation evidence. We did not optimize tokens by skipping tests or trusting summaries.

We also learned that independent review must come from a genuinely fresh execution. Asking the implementation agent to review its own work inside the same context does not provide meaningful independence. A fresh reviewer is more likely to challenge assumptions and discover defects.

Finally, local-first progressive enhancement is a strong default for a student-facing product. A learner can begin immediately without an account or stable internet connection, while cloud synchronization remains available as an optional improvement.

This project is still an early product, but it already gives my son a structured way to learn, practice, review mistakes, and prepare for exams.

For me, it demonstrates what a non-coder can build when AI agents are combined with clear ownership, evidence, testing, and human judgment.

What's next for Hoá học THCS

The next planned milestone is FEATURE-016, a read-only admin reporting dashboard.

  • Authorized admins can view each learner’s progress, XP, accuracy, review backlog, streak, and exam history.
  • The app will record active online study time only while lessons, reviews, or exams are visible and in use.
  • Daily reports will support 7-day, 30-day, and custom date ranges using the Vietnam timezone.
  • Supabase RLS will prevent students from seeing each other’s data or promoting themselves to admin.
  • The database migration will be tested and rolled back on a separate Supabase project before production.
  • As a CRITICAL security feature, it requires full testing and two independent reviews before release.

Built With

Share this project:

Updates