Skip to content

README.md

Latest commit

 

History

History
110 lines (91 loc) · 3.86 KB

README.md

File metadata and controls

110 lines (91 loc) · 3.86 KB

Sonus

Sonus is a multilingual language-learning platform focused on durable fluency through speaking practice, proficiency-aligned progression, and practical travel-first learning.

What Is This?

Sonus is a full-stack language-learning app in this monorepo:

  • Frontend: sonus-react/ (React + Vite + TypeScript)
  • Backend: backend/ (Fastify + Prisma + PostgreSQL)

Primary public surface: https://sonuslearning.com/

How the system fits together:

  • docs/SYSTEM_OVERVIEW.md (quick architecture map + diagram)
  • docs/ARCHITECTURE.md (deeper technical breakdown)
  • docs/PRODUCT_SCOPE.md (product identity and scope guardrails)

Why Sonus

Sonus exists to close the gap between vocabulary study and actually speaking in context. The product emphasizes:

  • Structured curriculum progression by language framework (for example, JLPT/TOPIK/CEFR-style tracks)
  • Active recall over passive review
  • Pronunciation practice with immediate feedback
  • Practical travel-first phrase training

Current Features

  • Multilingual product architecture (language-aware onboarding, profile, routing, and progression)
  • Japanese track with JLPT-style levels (n5 to n1) as the most complete curriculum today
  • Core study loop: Learn, Quiz, Speak, Apply
  • Weak-word detection and spaced review scheduling
  • Progress resume flow from home dashboard
  • Travel mode for phrase-first drills
  • Public landing + auth pages
  • Account/profile management

Tech Stack

  • Frontend: React 19, Vite 7, TypeScript, Tailwind CSS, PostCSS
  • Backend: Fastify 5, Prisma, TypeScript
  • Database: PostgreSQL
  • Testing: Vitest, Playwright
  • Tooling: npm workspaces, ESLint

Local Development

Prerequisites:

  • Node.js 20+
  • npm 10+
  • PostgreSQL 14+ (local install or Docker)

Setup:

npm install
cp backend/.env.example backend/.env
cp sonus-react/.env.example sonus-react/.env
npm run -w sonus-backend prisma:generate
npm run -w sonus-backend prisma:push
npm run dev

For PostgreSQL via Docker:

# In backend/ directory:
npm run db:up    # Starts postgres container
npm run db:down  # Stops container

Local endpoints:

  • Frontend: http://127.0.0.1:5173
  • Backend: http://127.0.0.1:4000

Environment Variables

  • Backend template: backend/.env.example
  • Frontend template: sonus-react/.env.example
  • Detailed reference: docs/ENV.md

Notes:

  • .env files are ignored by git.
  • Do not commit secrets or private tokens.
  • Production should use explicitly configured CORS and auth settings.

Commands

Most-used root commands:

  • npm run dev run frontend + backend
  • npm run dev:frontend run frontend only
  • npm run dev:backend run backend only
  • npm run build build all workspaces
  • npm test run backend + frontend test suites
  • npm run lint run lint checks

Project Status

Actively developed. Functional for end-to-end learning flows, but still evolving.

Known limitations:

  • Curriculum depth is uneven by language and level (Japanese is currently the most complete track).
  • UI/UX polish is ongoing in some flows.
  • Not positioned as production-perfect for every deployment topology yet.

Screenshots

Landing Page Choose a Language Home Dashboard Speaking Feedback Travel Sprint

Roadmap

  • Expand lesson depth and content quality across all bands
  • Improve pronunciation feedback quality and transparency
  • Add more progress analytics and personalized review recommendations
  • Harden deployment/ops workflows for broader public rollout
  • Continue performance and accessibility improvements

License

Proprietary. This code is for portfolio demonstration only. Unauthorized use, forking, or modification is prohibited. See LICENSE for details.