trying claude code so,

.gitignore

···
 public-jwk.json
 test-data/
 
-# Deciduous database (local)
+.claude/
 .deciduous/

CLAUDE.md

···
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
 # Project Instructions
 
 ## Decision Graph Workflow
···
 deciduous trace link <session_id> <node_id>   # Manual linking
 deciduous trace prune --days 30       # Cleanup old traces
 ```
+
+## Project Overview
+
+ATlast is a web application that helps users find their followed accounts from other social platforms (TikTok, Instagram, Twitter/X) on Bluesky/AT Protocol. Users upload their data export files, which are parsed for usernames, then searched in the AT Protocol network.
+
+## Development Commands
+
+### Local Development
+```bash
+# Mock mode (frontend only, no backend/OAuth/database)
+npm run dev:mock
+
+# Full mode (with backend, OAuth, database)
+npm run dev:full    # or npm run dev
+
+# Build for production
+npm run build
+
+# Initialize local database
+npm run init-db
+
+# Generate encryption keys for OAuth
+npm run generate-key
+```
+
+### Environment Configuration
+
+Two development modes supported:
+
+**Mock Mode** (.env.mock):
+- Set `VITE_LOCAL_MOCK=true`
+- No database or OAuth required
+- Uses MockApiAdapter for fake data
+
+**Full Mode** (.env):
+- Set `VITE_LOCAL_MOCK=false`
+- Requires PostgreSQL (local or Neon)
+- Requires OAuth keys and configuration
+- Must use `http://127.0.0.1:8888` (NOT localhost) for OAuth to work
+- See CONTRIBUTING.md for detailed setup
+
+## Architecture Overview
+
+### Frontend (React + TypeScript + Vite)
+
+**Core Structure:**
+- `src/pages/` - Page components (Login, Upload, Results, etc.)
+- `src/components/` - Reusable UI components
+- `src/lib/parsers/` - File parsing logic for different platforms
+- `src/lib/api/` - API client with adapter pattern (Real vs Mock)
+- `src/contexts/` - React contexts (SettingsContext for theme/preferences)
+- `src/hooks/` - Custom React hooks
+
+**API Client Pattern:**
+The app uses an adapter pattern for the API layer:
+- `src/lib/api/client.ts` - Factory that returns Real or Mock adapter based on ENV.IS_LOCAL_MOCK
+- `src/lib/api/adapters/RealApiAdapter.ts` - Calls Netlify Functions
+- `src/lib/api/adapters/MockApiAdapter.ts` - Returns fake data for frontend development
+- `src/lib/api/IApiClient.ts` - Interface both adapters implement
+
+**Platform Parsers:**
+- `src/lib/parsers/platformDefinitions.ts` - Defines parsing rules for each platform (Instagram, TikTok, etc.)
+- `src/lib/parsers/fileExtractor.ts` - Handles ZIP file uploads and extracts usernames
+- `src/lib/parsers/parserLogic.ts` - Implements extraction logic (HTML regex, JSON path traversal, TEXT regex)
+
+Each platform has multiple ParseRule entries defining:
+- `zipPath` - Location inside ZIP archive
+- `format` - "HTML" | "TEXT" | "JSON"
+- `rule` - Regex pattern string or JSON key path array
+
+### Backend (Netlify Functions)
+
+**Function Structure:**
+```
+netlify/functions/
+├── core/
+│   ├── middleware/        # Auth, error handling, session security
+│   ├── types/            # Shared types
+│   ├── errors/           # Custom error classes
+│   └── config/           # Configuration
+├── infrastructure/
+│   ├── oauth/            # OAuth client factory, stores
+│   ├── database/         # Database connection, service layer
+│   ├── cache/            # Caching utilities
+│   └── lexicons/         # AT Protocol lexicons
+├── services/             # Business logic (SessionService, FollowService, etc.)
+├── repositories/         # Data access layer
+└── utils/                # Shared utilities
+```
+
+**Key Functions:**
+- `oauth-start.ts` / `oauth-callback.ts` - AT Protocol OAuth flow
+- `session.ts` - Session management and validation
+- `batch-search-actors.ts` - Searches multiple usernames on Bluesky (includes ranking algorithm)
+- `check-follow-status.ts` - Checks if user follows specific DIDs
+- `batch-follow-users.ts` - Bulk follow operations
+- `save-results.ts` - Persists search results to database
+- `get-uploads.ts` - Retrieves user's upload history
+
+**Authentication Pattern:**
+All protected endpoints use:
+1. `withAuthErrorHandling()` middleware wrapper
+2. `AuthenticatedHandler` type (provides `context.sessionId`, `context.did`, `context.event`)
+3. `SessionService.getAgentForSession()` to get authenticated AT Protocol agent
+
+**Database:**
+- PostgreSQL via Neon serverless
+- Accessed through `DatabaseService` (infrastructure/database/)
+- Repositories pattern for data access (repositories/)
+
+**OAuth:**
+- AT Protocol OAuth using `@atproto/oauth-client-node`
+- OAuth client factory creates client with session/state stores
+- Private key (ES256) stored in `OAUTH_PRIVATE_KEY` env var
+- Public JWK served at `/jwks` endpoint
+- Must use `127.0.0.1` (not localhost) for local OAuth redirects
+
+### UI/Styling
+
+**Tailwind CSS with dual theme support:**
+- Light mode: purple/cyan color scheme
+- Dark mode: cyan/purple inverted
+- All components use `dark:` variant classes
+
+**Color System (from CONTRIBUTING.md):**
+- Text: purple-950/cyan-50 (primary), purple-750/cyan-250 (secondary)
+- Borders: cyan-500/purple-500 with opacity variants
+- Buttons: orange-600 (primary CTA), slate-600/700 (secondary)
+- Backgrounds: white/slate-900 (primary), purple-50/slate-900 (secondary)
+- Selected states: cyan-50 border-cyan-500 / purple-950/30 border-purple-500
+- Accents: orange-500/amber-500 (badges, progress)
+
+**Key Patterns:**
+- Mobile-first responsive design
+- List virtualization with `@tanstack/react-virtual` for large result sets
+- Code splitting and lazy loading for pages
+- Error boundaries throughout the app
+- Loading skeletons for async operations
+
+### Search & Matching Algorithm
+
+**Username Matching (batch-search-actors.ts):**
+The search uses a scoring system (0-100):
+1. Exact handle match (before first dot): 100
+2. Exact full handle match: 90
+3. Exact display name match: 80
+4. Partial handle match (contains): 60
+5. Partial full handle match: 50
+6. Partial display name match: 40
+7. Reverse partial match: 30
+
+All comparisons use normalized strings (lowercase, no special chars).
+Returns top 5 ranked results per username.
+
+**Result Enrichment:**
+- Fetches profiles in batches of 25 for post/follower counts
+- Checks follow status using custom lexicons (default: `app.bsky.graph.follow`)
+- Attaches follow status to each actor result
+
+## Key Technical Details
+
+### AT Protocol Integration
+- Uses `@atproto/api` for Bluesky API interactions
+- Uses `@atcute/identity-resolver` for DID resolution
+- Supports custom lexicons for experimental features
+- OAuth flow follows AT Protocol OAuth spec
+
+### File Upload Flow
+1. User uploads ZIP file (Instagram/TikTok data export)
+2. `fileExtractor.ts` reads ZIP in browser (using JSZip)
+3. Matches file paths to platform rules from `platformDefinitions.ts`
+4. `parserLogic.ts` extracts usernames (regex for HTML/TEXT, path traversal for JSON)
+5. Deduplicates and returns username list
+6. Frontend calls `/batch-search-actors` with username batches (max 50)
+7. Results stored in database via `/save-results`
+
+### Session Management
+- Session IDs stored in httpOnly cookies
+- Sessions linked to encrypted OAuth state stores
+- Session validation middleware checks database and expiry
+- Sessions tied to specific DIDs (user accounts)
+
+### Deployment
+- Hosted on Netlify
+- Static frontend built with Vite
+- Serverless functions for backend
+- Database on Neon (PostgreSQL)
+- OAuth redirects configured in netlify.toml
+
+## Adding New Features
+
+### Adding a New Social Platform
+1. Add parsing rules to `src/lib/parsers/platformDefinitions.ts`:
+```typescript
+export const PLATFORM_RULES: Record<string, ParseRule[]> = {
+  newplatform: [
+    {
+      zipPath: "path/in/zip/file.json",
+      format: "JSON",
+      rule: ["key", "path", "to", "username"],
+    },
+  ],
+};
+```
+2. Test with real data export from that platform
+3. Update UI in platform selection components
+
+### Adding a New API Endpoint
+1. Create function in `netlify/functions/your-endpoint.ts`
+2. Use `withAuthErrorHandling()` for protected endpoints
+3. Implement `AuthenticatedHandler` type
+4. Add method to `IApiClient.ts` interface
+5. Implement in both `RealApiAdapter.ts` and `MockApiAdapter.ts`
+6. Use via `apiClient.yourMethod()` in components
+
+### Adding Database Models
+1. Create migration script in `scripts/`
+2. Run against local database
+3. Update repository in `netlify/functions/repositories/`
+4. Update DatabaseService if needed
+
+## Important Notes
+
+- **OAuth Localhost Issue**: Must use `127.0.0.1:8888` not `localhost:8888` for local OAuth to work
+- **Batch Limits**: Search endpoint limited to 50 usernames per request
+- **Profile Fetching**: Batched in groups of 25 to avoid rate limits
+- **Normalization**: All username comparisons use lowercase + special char removal
+- **Security**: CSP headers configured in netlify.toml, session security middleware prevents CSRF
+- **Error Handling**: Custom error classes (ValidationError, AuthenticationError, etc.) with proper HTTP status codes