CERF-Evaluation-App is a full-stack web application designed to provide language learners with instant, detailed, and actionable feedback on their English writing. By leveraging a powerful Large Language Model, it acts as an on-demand AI tutor, analyzing text against the Common European Framework of Reference for Languages (CEFR) to help users improve their skills effectively.
This project was built from the ground up to showcase a modern, secure, and highly interactive web application that solves a real-world problem for language learners. It demonstrates advanced concepts like real-time data streaming, multi-layered API security, and complex state management.
- Instant AI Evaluation: Submit English text for a writing task and receive a comprehensive analysis in seconds.
- Detailed CEFR Report: Get an overall CEFR level (A1-C2), positive highlights, and a full feedback report.
- Category Breakdown: See your performance rated across Grammar, Vocabulary, Fluency, and Cohesion.
- Interactive Highlighting: Errors and suggestions are highlighted directly in your text. Hover for detailed explanations and corrections.
- Persistent History: All your past evaluations are saved to your browser's
localStorage, allowing you to track your progress over time. - Task-Based Practice: Choose from a variety of writing prompts to keep your practice sessions focused and contextual.
- Real-Time Streaming: The AI's response is streamed to the UI, providing a fast, responsive experience without long loading spinners.
- Multi-Layered API Security: The evaluation endpoint is protected against abuse and bots to control costs and ensure availability.
- Bot Protection: Integrates BotID to block automated scripts before they can make a request.
- Rate Limiting: Uses Upstash Redis to limit the number of requests per user, preventing spam.
- Developer Bypass: A secret key allows for unlimited testing during development.
This project is built with a modern, type-safe stack using the Next.js App Router.
- Framework: Next.js 15 (App Router)
- Language: TypeScript
- AI & Streaming: Vercel AI SDK (
experimental_useObject) to stream structured JSON from the AI model directly to the UI. - LLM Provider: OpenRouter (utilizing the
google/gemini-flash-2.0model). - Styling: Tailwind CSS with shadcn/ui for primitive components.
- State Management: Zustand with
persistmiddleware for both core app state and user settings. - Schema Validation: Zod to enforce the structure of the AI's output and validate API requests.
- Deployment: Vercel
- Structured JSON Streaming: The application's core innovation is its ability to stream a complex, structured JSON object from the AI in real-time. By pairing the Vercel AI SDK with a Zod schema, the app ensures the AI's output is always valid and type-safe from the server to the client, enabling a dynamic and reliable UI.
- Decoupled & Persistent State: State is managed with two separate Zustand stores—one for the app's ephemeral state and another for persistent user settings. This clean separation simplifies complex features, which seamlessly passes state between components without prop drilling.
- Robust API Security: All critical operations are handled on the server. The evaluation endpoint is heavily fortified with multiple layers of security to prevent automated abuse, a critical feature for an application that relies on a pay-per-use AI service.
- Responsive and Accessible UI: The interface is built with Tailwind CSS and shadcn/ui, ensuring it is fully responsive and accessible across all devices.
- Node.js (v22.x or higher)
- pnpm (or your preferred package manager)
- An Upstash Redis database (for rate limiting)
- An OpenRouter API key
-
Clone the repository:
git clone https://github.com/DiegoxK/CERF-Evaluation-App.git cd CERF-Evaluation-App -
Install dependencies:
pnpm install
-
Set up environment variables: Create a file named
.envin the project root by copying the example file:cp .env.example .env
Open
.envand fill in all the required values (Upstash, OpenRouter, etc.). -
Run the development server:
pnpm run dev
The application will be available at http://localhost:3000.
To run this project, you need to configure the following variables in your .env file:
# OpenRouter API Key for AI model access
OPENROUTER_API_KEY=""
# Upstash Redis credentials for rate limiting
UPSTASH_REDIS_REST_URL=""
UPSTASH_REDIS_REST_TOKEN=""
# A secret key to bypass rate limiting and bot protection during development
INTERNAL_API_SECRET=""Diego Suarez - SynthCode
- Email: diego.synthcode@gmail.com