Project Info
Inspiration
We were inspired by the need for better accessibility tools for students with special needs. Observing the struggle of these students in accessing reading materials, and the lack of adaptive technologies in schools to support their unique learning requirements, motivated us to develop a solution. Our frustration stemmed from the gap in resources that should be helping these students succeed. ReadOn was born out of a desire to bridge this gap and provide an inclusive tool that empowers students with special needs to access educational content more effectively.
What it does
ReadOn is an accessible reading assistant designed to cater to students with different learning abilities. It simplifies text, generates voiceovers, and uses adaptive reading speeds based on the user’s needs. The app can highlight key information, break down complex paragraphs, and convert text to audio for students who struggle with traditional reading methods. By using ReadOn, students can customize their reading experience to suit their personal needs, improving comprehension and retention of material.
How we built it
We built ReadOn using Next.js for the frontend, ensuring a fast and responsive user experience. The app integrates with natural language processing (NLP) APIs to provide text simplification and summary features. We used text-to-speech libraries to convert text into audio, making the content accessible for users with visual impairments or dyslexia. The backend is powered by Node.js. We also focused on making the user interface intuitive and easy to navigate, ensuring that students and educators can use the tool without a steep learning curve.
Challenges we ran into
One of the major challenges we faced was integrating an accurate and responsive text-to-speech feature that could handle a wide range of educational content without errors. Specifically, we encountered difficulties with phonetic breakdowns, as many words have multiple pronunciations or complex phonetic structures. Ensuring that the text-to-speech system correctly pronounced these words based on context proved to be a significant hurdle. Additionally, optimizing the application’s performance when processing large documents in real-time, while ensuring that all accessibility features like accurate phonetics were properly implemented, presented further obstacles. Balancing these needs without sacrificing user experience was one of our biggest technical hurdles.
Accomplishments we're proud of
We’re proud of building an application that can truly make a difference in the lives of students with special needs. Creating an adaptable, multi-functional reading tool that simplifies content while keeping it engaging and accessible is an achievement we’re excited about. Additionally, we successfully integrated key accessibility features like audio generation, customizable reading levels, and visual aids that enhance the overall user experience. Most importantly, we are proud that this tool can empower students who have previously struggled with traditional learning methods.
What we learned
Throughout this journey, we learned the importance of accessibility in education and how small changes in technology can significantly impact the learning experience for students with special needs. We also deepened our understanding of text processing, audio synthesis, and front-end optimization to create a seamless and supportive user experience. Additionally, we gained valuable insight into how inclusive design principles can be applied to software development, ensuring that the app caters to a diverse set of users.
What's next
Looking ahead, we plan to incorporate AI-driven personalization to automatically adjust reading levels and recommend content based on each user’s progress. We aim to further improve text summarization and make the app compatible with a wider range of devices, including mobile phones and tablets. Our next steps include building a comprehensive dashboard for teachers, where they can monitor their students’ progress and provide personalized guidance. Finally, we hope to collaborate with schools and educational institutions to bring ReadOn into classrooms and assist a larger population of students in their learning journey.
Read On
Read On is a reading support platform with four learner-facing capabilities:
- phonics and pronunciation support
- reading comprehension activities
- story visualization
- audiobook/read-aloud playback
The app uses a story-centric flow: generate a story once, then access all features by storyId from /features/[storyId].
Repository Structure
ReadOn/
├── src/app/ # Next.js routes and API handlers
├── views/ # UI components and page views
├── orchestrators/ # BFF/service composition layer
├── microservices/ # phonics, comprehension, image-generation, audiobook, dashboard
├── shared/ # shared clients, types, constants
├── ops/gcp/ # deploy/provision/verify scripts
└── docs/ # architecture and operations docs
Core Architecture
- Frontend: Next.js + Chakra UI
- Backend-for-Frontend: orchestrators in the Next app
- Services: independent microservices for each feature area
- Data ownership: story and feature data are loaded by
storyId, with route-level ownership checks in BFF APIs
Running the App (local dev)
The Next app and microservices run as separate processes.
- Install dependencies:
npm install
npm --prefix microservices/phonics-service install
npm --prefix microservices/comprehension-service install
npm --prefix microservices/image-generation-service install
npm --prefix microservices/audiobook-service install
npm --prefix microservices/dashboard-service install
- Copy env templates and configure values:
cp .env.example .env
cp microservices/phonics-service/.env.example microservices/phonics-service/.env
cp microservices/comprehension-service/.env.example microservices/comprehension-service/.env
cp microservices/image-generation-service/.env.example microservices/image-generation-service/.env
cp microservices/audiobook-service/.env.example microservices/audiobook-service/.env
cp microservices/dashboard-service/.env.example microservices/dashboard-service/.env
- Start services:
npm run dev:all
Or start individually with npm run dev, npm run dev:phonics, npm run dev:comprehension, npm run dev:image-generation, npm run dev:audiobook, and npm run dev:dashboard.
Local Ports
| Process | Port |
|---|---|
| Main Next.js app | 3000 |
| phonics-service | 3001 |
| comprehension-service | 3002 |
| image-generation-service | 3003 |
| audiobook-service | 3004 |
| dashboard-service | 3005 |
Main Routes
/(story input + generate)/dashboard/features/[storyId](feature hub)/phonics,/comprehension,/visualization,/audiobook(feature entry pages)/audiobook/player/story/[id]/auth
Validation Commands
npm run lint
npm run test
npm run verify:services
npm run verify:endpoints
Deployment (Google Cloud Run)
Deployment is script-driven from ops/gcp/ (no built-in auto-deploy workflow in this repo).
- Provision:
bash ops/gcp/provision.sh - Deploy stack:
READON_DEPLOY_ENV=prod|test SERVICE_VERSION=<git-sha> bash ops/gcp/deploy-stack.sh - Verify:
READON_DEPLOY_ENV=prod|test bash ops/gcp/verify/verify-health.sh
Documentation
- Architecture: docs/architecture.md
- Deployment guide: docs/deployment-guide.md
- CI/CD overview: docs/cicd-overview.md
- Env reference: docs/environment-variables.md
Analysis
View
Metric
- 8
- 8
- 3
Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.
Technology
- CSSIn code
- ExpressIn code
- JavaScriptIn code
- Next.jsIn code
- PostgreSQLIn code
- ReactIn code
- SQLIn code
- TypeScriptIn code
- Google GeminiClaimed
- OpenAIClaimed
8 of 10 appear in the indexed code. 2 claimed on Devpost could not be matched to code, which may simply mean the tool leaves no trace in the repository.
AI coding agents
- CursorCommits
Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.
Codebase size
Source size
654 KB
Source files
267
Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.
Repository
aadhilmsyed/ReadOn
331 files · 3.3 MB · @ 1c667e5
Structure
Interface
35 files · 11%Screens, components and styles rendered to the user.
+2 moreAPI & routing
39 files · 12%Request entry points: routes, handlers and controllers.
Application logic
119 files · 36%Domain rules, services and shared utilities.
+16 moreData & schema
21 files · 6%Schema definitions, migrations and data access.
Supporting
Layers are inferred from where files sit in the tree, not from reading the code. A project that names its directories unconventionally will read oddly here — open the file browser to check anything the diagram implies.
Languages
- TypeScript64%
- JavaScript13%
- Shell9%
- Markdown9%
- YAML4%
- SQL1%
- Other (1)0%
Share of indexed source by file size. Binary and vendored files are excluded.
Dependencies
package.json
npm · 27- @chakra-ui/react
- @emotion/react
- @emotion/styled
- @types/express
- bcryptjs
- compromise
- express
- jose
- next
- pg
- react
- react-dom
- react-icons
- react-pageflip
- zod
- +12 more
microservices/image-generation-service/package.json
npm · 12- @google-cloud/storage
- @google-cloud/vertexai
- @types/cors
- cors
- dotenv
- express
- pg
- +5 more
microservices/phonics-service/package.json
npm · 10- compromise
- dotenv
- express
- pg
- tsx
- zod
- +4 more
microservices/audiobook-service/package.json
npm · 7- @google-cloud/text-to-speech
- dotenv
- express
- tsx
- +3 more
microservices/comprehension-service/package.json
npm · 3- @google-cloud/vertexai
- dotenv
- pg
microservices/dashboard-service/package.json
npm · 3- dotenv
- express
- pg
Declared in the repository’s manifests at the indexed commit. A declared package is not proof it is used, and runtime dependencies are listed first.
This project’s features have not been analysed yet.
Export this project's context (description, README, evidence, key source files) to chat with an AI agent elsewhere.