README.md

---
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

```bash
npm install
```

### 2. Supabase Database Setup

#### Create Tables
Run these SQL queries in your Supabase SQL Editor:

```sql
-- 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:

```sql
-- 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:
   ```bash
   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

```bash
npm run dev
```

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

## Environment Variables

Required environment variables (see `.env.example`):

```env
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`)
```json
{
  "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`)
```json
{
  "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

```bash
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