instalens

README preview

# InstaLens (Working Codename)

Internal codename: `InstaLens`.
Note: this codename should be used publicly or in the App due Instagram/Meta trademark restrictions.

## Overview

InstaLens is a React + TypeScript web app backed by Supabase that helps creators analyze Instagram post performance and generate AI content briefs from what is already working.

Core workflow:
1. User signs up/signs in with Supabase Auth.
2. User connects Instagram via OAuth.
3. App syncs media + insights into Supabase.
4. Platform computes per-post scores based on the user's goal (Growth, Leads or other to be defined).
5. Recommendations page extracts patterns and generates new content briefs via an Edge Function and AI.
6. User select the best recommendations and the platform generates new content based on the selected recommendations.
7. Platform help user to create the content and post it to Instagram.
8. Platform help user to decide best day and time to post.
9. Platform show content calendar to support user manage their socila midia strategy
10. Platform help user to analyze the results and improve the strategy.

## Proposed Tech Stack

- Frontend: React 19, TypeScript, Vite 7
- Routing: React Router 7
- Styling: Tailwind CSS v4 (theme tokens in `src/index.css`)
- Backend: Supabase (Auth, Postgres, RLS, Realtime, Edge Functions)
- Testing: Vitest + Testing Library + jsdom
- AI generation: APIs (via Supabase Edge Function) - Allow configure APIs for Claude, Gemini and OpenAI

## Proposed Product Features

- Email/password authentication (Supabase Auth)
- Protected app routes and shared shell layout
- Instagram OAuth connect flow
- On-demand sync windows: 30 / 90 / 180 / 360 days
- Live sync status via Supabase Realtime
- Sync state handling: `pending`, `syncing`, `complete`, `partial`, `error`
- Dashboard with:
  - media filters (All, Images, Carousels, Reels)
  - sorting by timestamp, reach, engagement rate, score
  - per-post score badges
- Post detail view with:
  - metric cards
  - median deltas
  - score breakdown and improvement hints
- Recommendations with:
  - top-performer detection (top 20%)
  - pattern extraction (format mix, captions, hashtags, CTA, posting time)
  - AI-generated content briefs
- Strategy and Posts sugestions
- Content Calendar
- Posts creation
- Post to Instagram (Phase 2)
- Analyze results
- Improve strategy


## Scoring Model

Scoring is computed client-side (?) using p95 normalization across the account's posts:

- Growth weights:
  - distribution (shares/reach): 30%
  - saves/reach: 25%
  - comments/reach: 15%
  - follows/reach: 20%
  - retention: 10%

- Leads weights:
  - value (saves/reach): 30%
  - distribution (shares/reach): 20%
  - consideration (profile visits/reach): 25%
  - follows/reach: 15%
  - CTA keyword signal: 10%

- Other ?