# 📱 Farcastle Notifications – Mini App Spec

### Overview
Farcastle Notifications is a Warpcast mini app that enables users to receive real-time alerts on Farcastle DAO activity. Users can customize the types of notifications they receive and manage their preferences through a lightweight interface.

---

### 🎯 Core Use Cases
- **User Authentication**
- Warpcast sign-in and identity linking.
- **Notification Opt-In**
- Users can enable notifications via the mini app UI.
- **Notification Configuration**
- Toggle notification types:
- Proposal created
- Proposal voting period closing soon
- Proposal passed/failed
- Fundraiser created
- Fundraiser closing soon
- Fundraiser with high activity
- DAO-specific filtering
- **Global Control**
- Master toggle to disable all notifications

---

### ⚙️ Technical Stack

#### Frontend
- **Framework**: Next.js
- **UI Mode**: Warpcast Mini App Frame
- **Pages**:
- Landing page with login + enable notifications
- Preferences dashboard (manage toggles, DAO filter)

#### Backend (API)
- **Framework**: Next.js API routes
- **Endpoints**:
- `POST /api/events/addFrame`: Handles `addFrame` webhook
- `POST /api/events/notificationsEnabled`: Handles `notificationsEnabled`
- `POST /api/events/notificationsDisabled`: Handles `notificationsDisabled`
- `POST /api/events/frameRemoved`: Handles `frameRemoved`
- `POST /api/user/preferences`: Updates user preferences

#### Jobs / Background Tasks

Background workers are responsible for polling DAO data and sending notifications without duplicates.

#### Responsibilities
- Regularly poll DAO subgraphs for:
- New proposals
- Upcoming proposal deadlines
- Proposal outcomes
- Fundraiser activity
- Match fetched events with user preferences
- Trigger notifications via Warpcast Mini App API

#### 🧠 Deduplication Strategy (Hybrid Approach)
To avoid duplicate notifications:

1. **Event ID Tracking (Persistent)**
- Track every event notified per user
- Ensure no user receives the same notification twice
2. **Timestamp-based Polling**
- Maintain a `last_poll_time` per job type
- Only fetch events after that time
3. **Optional Caching Layer**
- Redis or in-memory cache for fast-checking during job runs

#### 📄 Supabase Schema Updates

**Table: `processed_events`**
| Column | Type | Description |
|-----------------|-----------|------------------------------------------|
| `id` | UUID | Primary key |
| `event_type` | TEXT | e.g., `proposal_created`, `fundraiser` |
| `entity_id` | TEXT | Unique ID from DAO subgraph |
| `user_id` | UUID | FK to users table |
| `notified_at` | TIMESTAMP | When the notification was sent |

- Unique constraint on (`event_type`, `entity_id`, `user_id`) to prevent duplicates.
- Indexes on `event_type` and `notified_at` for efficient querying.

**Optional Table: `job_metadata`**
| Column | Type | Description |
|------------------|-----------|-------------------------------------|
| `job_name` | TEXT | e.g., `poll_proposals` |
| `last_poll_time` | TIMESTAMP | Last successful polling timestamp |

---

### 🗃️ Data Storage (Supabase)
- **Users Table**
- `id` (UUID)
- `farcaster_id`
- `notification_token`
- `enabled` (bool)
- **Preferences Table**
- `user_id` (FK)
- `proposal_created` (bool)
- `proposal_closing` (bool)
- `proposal_outcome` (bool)
- `fundraiser_created` (bool)
- `fundraiser_closing` (bool)
- `fundraiser_trending` (bool)
- `dao_filters` (array/text)

---

### 🔔 Notification Flow
1. User enables notifications via mini app
2. Token is stored in Supabase
3. Worker polls DAO subgraphs regularly
4. Matches triggers with user preferences
5. Sends personalized notification through Warpcast API

---

### 🔗 Resources
- [Warpcast Mini App Docs](https://miniapps.farcaster.xyz/)
- [Notification Guide](https://miniapps.farcaster.xyz/docs/guides/notifications)
- [Farcastle](https://farcastle.net/)
- [Mini Apps for LLMs](https://miniapps.farcaster.xyz/llms-full.txt)

---

Want help turning this into a task breakdown, API schema, or early mockups next?

---

## scratch

A warpcast mini app where a warpcast user can recieve notification on Farcastle DAO activity.

**Use cases**
- users can sign in
- users can opt into notifications
- users can configure the notification types
- turn types on/off
- proposal created
- proposal voting period closing soon
- proposal pass or failed
- fundraiser created
- fundraiser closing soon
- fundraiser getting lots of contributions
- configure specific details
- which dao(s) to get proposal details about
- users can turn off all notification

**Technical details**
- web application in next.js with ui/app endpoints and api endpoints
- supabase database to
- store [user/token data](https://miniapps.farcaster.xyz/docs/guides/notifications#save-the-notification-tokens) for opted in user on warpcast
- store notification preferences for the opted in users
- ui is a warpcast [mini app](https://miniapps.farcaster.xyz/)
- simple page to signup and manage notifications
- api needs to
- listen to webhook event addFrame and notificationsEnabled from [warpcast](https://miniapps.farcaster.xyz/docs/guides/notifications#listen-for-events)
- [addFrame](https://miniapps.farcaster.xyz/docs/sdk/events#frameadded)
- [notifcationsEnabled](https://miniapps.farcaster.xyz/docs/sdk/events#notificationsenabled)
- listen to disable notification events to opt users out of notifications
- [notificationsDisabled](https://miniapps.farcaster.xyz/docs/sdk/events#notificationsenabled)
- [frameRemoved](https://miniapps.farcaster.xyz/docs/sdk/events#frameremoved)
- endpoint to update notfication preferences/configuration
- Jobs/processes to look at data from DAO subgraphs and trigger appropriate users

## Helpful links
[Mini app docs](https://miniapps.farcaster.xyz/)
[mini app docs for llms](https://miniapps.farcaster.xyz/llms-full.txt)
[farcastle overview](https://farcastle.net/)