README.md

metadata

title: Brainstorm Ui
emoji: 🌍
colorFrom: pink
colorTo: yellow
sdk: docker
pinned: false

English Test Brainstorming App

A modern web application for browsing and practicing CELPIP-style speaking and writing tasks with brainstorming prompts, curated vocabulary, and sample responses. Features mandatory user authentication, task tracking, and progress management with Supabase integration.

Features

• Authentication: Users must log in to access any content
• Task Tracking: Mark tasks as completed to avoid re-practicing
• Supabase Integration: Real database for user authentication and progress tracking
• Responsive Design: Works on desktop and mobile devices
• Advanced Filtering: Filter by category, task type, and completion status

Prerequisites

• Node.js (v16 or higher)
• npm or yarn
• Supabase account and project

Setup Instructions

1. Install Dependencies

npm install

2. Supabase Database Setup

Create Tables

Run these SQL queries in your Supabase SQL Editor:

-- Task completions table for tracking progress
CREATE TABLE completed_tasks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
    task_id VARCHAR(50) NOT NULL,
    task_type VARCHAR(50) NOT NULL,
    category VARCHAR(20) NOT NULL,
    completed_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    UNIQUE(user_id, task_id, task_type)
);

-- Indexes for better performance
CREATE INDEX idx_completed_tasks_user_id ON completed_tasks(user_id);

Enable Supabase Auth

Go to your Supabase project dashboard:

1. Authentication -> Settings -> Enable email/password authentication
2. Authentication -> Email Template -> Configure confirmation email template
3. Authentication -> Settings -> Set your site URL for redirects

Set Up Row Level Security (RLS)

Enable RLS for proper security with Supabase Auth:

-- Enable RLS on `completed_tasks` table
ALTER TABLE completed_tasks ENABLE ROW LEVEL SECURITY;

-- Users can only see their own completions
CREATE POLICY "Users can view own completions" ON completed_tasks
    FOR SELECT USING (auth.uid() = user_id);

-- Users can only insert their own completions
CREATE POLICY "Users can insert own completions" ON completed_tasks
    FOR INSERT WITH CHECK (auth.uid() = user_id);

-- Users can only update their own completions
CREATE POLICY "Users can update own completions" ON completed_tasks
    FOR UPDATE USING (auth.uid() = user_id);

-- Users can only delete their own completions
CREATE POLICY "Users can delete own completions" ON completed_tasks
    FOR DELETE USING (auth.uid() = user_id);

Create Test Users

Use the Supabase Auth UI or API to create test users:

1. Go to Authentication -> Users in your Supabase dashboard
2. Click Add user and create test accounts
3. Or use the signup functionality in your app

3. Environment Configuration

1. Copy the example environment file:

   cp .env.example .env
   

2. Fill in your Supabase credentials:

   • Go to your Supabase project dashboard
   • Settings -> API
   • Copy the Project URL and anon/public key

4. Prepare Data Files

Place your data files in the ./data/ directory:

• speaking.jsonl - Speaking tasks data
• writing.jsonl - Writing tasks data

5. Run the Development Server

npm run dev

The application will be available at http://localhost:4323

Environment Variables

Required environment variables (see .env.example):

SUPABASE_URL=your_supabase_project_url
SUPABASE_ANON_KEY=your_supabase_anon_key

Usage

Authentication

• Login: Users must log in with email and password to access any content
• Session: Sessions are managed automatically by Supabase (persistent)
• Logout: Clears session and shows login screen

Task Management

• Browse: Filter tasks by category, type, and completion status
• Track: Mark tasks as completed to track progress
• Avoid Repetition: Completed tasks can be filtered out

Data Structure

Speaking Tasks (speaking.jsonl)

{
  "id": "unique_id",
  "task_type": "giving_advice",
  "category": "Speaking",
  "rephrased_task": "Task description...",
  "brainstorm": [{"title": "Idea", "description": "Description"}],
  "vocabulary": ["word1", "word2"],
  "response": "Sample response..."
}

Writing Tasks (writing.jsonl)

{
  "id": "unique_id",
  "task_type": "writing_email",
  "category": "Writing",
  "rephrased_task": "Task description...",
  "brainstorm": [{"title": "Idea", "description": "Description"}],
  "response": "Sample response..."
}

Development

Project Structure

astra/
├── src/
│   ├── components/     # Astro components
│   ├── layouts/       # Layout components
│   ├── pages/         # Page components
│   ├── styles/        # Global styles
│   └── utils/         # Utility functions
├── data/              # JSON data files
├── public/            # Static assets
└── scripts/           # Build scripts

Key Components

• src/pages/index.astro - Main application page
• src/components/LoginForm.astro - Authentication form
• src/layouts/BaseLayout.astro - Base layout component

Authentication Flow

1. Page loads -> Check Supabase auth session
2. If no session -> Show login overlay, hide content
3. User submits form -> Authenticate with Supabase Auth
4. If successful -> Supabase manages session, show content
5. Session persists automatically (managed by Supabase)

Security Notes

• Important: Now uses Supabase Auth for secure authentication
• Row Level Security (RLS) ensures users can only access their own data
• Supabase handles password hashing and session management securely
• Use HTTPS in production
• RLS policies prevent unauthorized access to user data
• No sensitive data exposed in frontend code

Troubleshooting

Common Issues

1. Login form not working

   • Check browser console for JavaScript errors
   • Verify Supabase credentials are correct
   • Ensure database tables exist

2. Data not loading

   • Check that JSONL files are in the correct format
   • Verify file paths in the data loading functions
   • Check browser network tab for 404 errors

3. Authentication issues

   • Verify Supabase URL and keys are correct
   • Check that users exist in the database
   • Ensure RLS policies are set up correctly

Build for Production

npm run build
npm run preview

Deployment

The app can be deployed to any static hosting service that supports environment variables:

• Hugging Face Spaces
• Vercel
• Netlify
• Cloudflare Pages