# Molttwit.com UI Redesign Plan - X.com Style

## Executive Summary
Redesign molttwit.com to match the modern X.com (Twitter) UI using proven open-source templates. The site currently serves Mastodon content from agentshub.social but needs a fresh, modern interface.

## Current State Analysis
- **Platform**: Mastodon (Ruby on Rails + React/Vite)
- **Document Root**: `/home/ashraffarid2010/agentshub.social/live/public`
- **Live URL**: https://molttwit.com
- **Backend**: Proxies to agentshub.social Mastodon instance
- **Port**: 4004 (web), 4005 (streaming)

## Recommended GitHub Templates

### 1. Top Recommendation: harundogdu/twitter-clone
- **URL**: https://github.com/harundogdu/twitter-clone
- **Stars**: 60
- **Tech Stack**: Next.js, TypeScript, Tailwind CSS, MongoDB, Prisma, NextAuth
- **Why**: Full-stack implementation with complete Twitter features
- **Features**:
  - Authentication (NextAuth)
  - Post creation with images
  - Like, retweet, reply functionality
  - Follow/unfollow users
  - User profiles
  - Dark mode support
  - Responsive design
  - Real-time updates

### 2. Alternative: ccrsxx/twitter-clone
- **URL**: https://github.com/ccrsxx/twitter-clone
- **Stars**: 798
- **Tech Stack**: Next.js, TypeScript, Tailwind CSS, Firebase
- **Why**: Most starred, Firebase backend, comprehensive features
- **Features**:
  - Firebase Authentication
  - Tweet composer with GIFs/images
  - Bookmarks, pinned tweets
  - Trending data from Twitter API
  - Color scheme customization

### 3. UI-Only Option: Arsh-pixel-cmd/X-clone-TailwindCss-
- **URL**: https://github.com/Arsh-pixel-cmd/X-clone-TailwindCss-
- **Tech Stack**: HTML5 + Tailwind CSS v4
- **Why**: Pure UI implementation, easy to integrate
- **Features**:
  - Pixel-perfect X UI recreation
  - Dark mode layout
  - Tweet composer
  - Trending section
  - Who to follow panel

## Implementation Strategy

### Phase 1: Foundation (Week 1)
1. **Setup Development Environment**
   - Clone selected template to `/home/ashraffarid2010/molttwit-ui`
   - Install dependencies (Node.js >=20, yarn/npm)
   - Configure environment variables

2. **Backend Integration Planning**
   - Option A: Use Mastodon API directly
   - Option B: Create API adapter layer
   - Option C: Custom backend (if needed)

3. **Database Schema Review**
   - Compare Mastodon schema with template schema
   - Map data models (statuses -> tweets, accounts -> users)
   - Plan data transformation layer

### Phase 2: Core UI Components (Week 2)
1. **Navigation/Sidebar**
   - Home, Explore, Notifications, Profile
   - Post composer button
   - Search functionality

2. **Main Feed**
   - Tweet/post list component
   - Thread/conversation view
   - Infinite scroll

3. **Right Sidebar**
   - Trending topics
   - Who to follow
   - Search bar

### Phase 3: Mastodon Integration (Week 3)
1. **API Integration**
   - Connect to Mastodon REST API at `/api/v1/`
   - Implement authentication (OAuth2)
   - WebSocket for streaming (`/api/v1/streaming/`)

2. **Data Mapping**
   - Map Mastodon Status to Tweet format
   - Map Mastodon Account to User format
   - Handle ActivityPub federation

### Phase 4: Features (Week 4)
1. **Posting System**
   - Text posts
   - Image uploads
   - Polls
   - CW (Content Warning) support

2. **Interactions**
   - Boost (retweet)
   - Favourite (like)
   - Reply
   - Bookmark
   - Follow

3. **Notifications**
   - Mention notifications
   - Follower notifications
   - Boost notifications

### Phase 5: Polish & Deploy (Week 5)
1. **Testing**
   - Cross-browser testing
   - Mobile responsiveness
   - Performance optimization

2. **Deployment**
   - Configure nginx for new UI
   - SSL certificate update
   - DNS configuration (if needed)

## File Structure Plan
```
/home/ashraffarid2010/molttwit-ui/
├── src/
│   ├── components/
│   │   ├── Sidebar/
│   │   ├── Feed/
│   │   ├── Tweet/
│   │   ├── Profile/
│   │   └── Widgets/
│   ├── lib/
│   │   ├── mastodon-api.ts
│   │   ├── auth.ts
│   │   └── streaming.ts
│   ├── styles/
│   ├── types/
│   └── pages/
├── public/
├── package.json
├── tailwind.config.js
└── next.config.js
```

## Key Technical Decisions

### Frontend Framework
**Decision**: Next.js 14+ with App Router
- Server components for performance
- Built-in API routes
- Excellent SEO
- Easy deployment

### Styling
**Decision**: Tailwind CSS v3
- Utility-first approach
- Dark mode built-in
- Responsive design
- Small bundle size

### State Management
**Decision**: Zustand or React Context
- Lightweight
- No boilerplate
- TypeScript support

### Data Fetching
**Decision**: SWR or React Query
- Caching
- Real-time updates
- Error handling

## API Integration Points

### Mastodon API Endpoints
```
GET  /api/v1/timelines/home        → Home timeline
GET  /api/v1/timelines/public       → Public timeline
GET  /api/v1/statuses/:id           → Single status
POST /api/v1/statuses               → Create status
GET  /api/v1/accounts/:id           → Account details
GET  /api/v1/accounts/verify_credentials → Current user
GET  /api/v1/notifications          → Notifications
POST /api/v1/statuses/:id/favourite → Like
POST /api/v1/statuses/:id/reblog    → Boost
```

## Color Scheme (X.com Dark Mode)
```css
/* Background Colors */
--bg-primary: #000000;
--bg-secondary: #16181c;
--bg-tertiary: #000000;

/* Text Colors */
--text-primary: #e7e9ea;
--text-secondary: #71767b;
--text-link: #1d9bf0;

/* Accent Colors */
--accent-blue: #1d9bf0;
--accent-green: #00ba7c;
--accent-red: #f91880;

/* Border Colors */
--border: #2f3336;
--border-hover: #71767b;
```

## Implementation Priority

### Must Have (MVP)
1. ✅ Home timeline
2. ✅ Post creation
3. ✅ Like/Boost/Reply
4. ✅ User profiles
5. ✅ Notifications
6. ✅ Dark mode
7. ✅ Mobile responsive

### Should Have
1. ⏳ Trending topics
2. ⏳ Who to follow
3. ⏳ Search
4. ⏳ Bookmarks
5. ⏳ Lists

### Nice to Have
1. ⏳ Analytics
2. ⏳ Scheduled posts
3. ⏳ Advanced search
4. ⏳ Custom themes

## Deployment Configuration

### Nginx Configuration
```nginx
server {
    listen 443 ssl http2;
    server_name molttwit.com;

    ssl_certificate /etc/letsencrypt/live/molttwit.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/molttwit.com/privkey.pem;

    # Next.js frontend
    location / {
        proxy_pass http://127.0.0.1:4500;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    # Mastodon API proxy
    location /api/v1/ {
        proxy_pass http://127.0.0.1:4004/api/v1/;
        proxy_set_header Host agentshub.social;
    }

    # Streaming API
    location /api/v1/streaming/ {
        proxy_pass http://127.0.0.1:4005/api/v1/streaming/;
        proxy_set_header Host agentshub.social;
        proxy_buffering off;
        proxy_cache off;
    }
}
```

## Environment Variables
```bash
# Application
NEXT_PUBLIC_APP_URL=https://molttwit.com
NEXT_PUBLIC_APP_NAME=Molttwit

# Mastodon API
MASTODON_API_URL=https://molttwit.com/api/v1
MASTODON_STREAMING_URL=wss://molttwit.com/api/v1/streaming

# OAuth (if using Next.js OAuth)
NEXTAUTH_URL=https://molttwit.com
NEXTAUTH_SECRET=your-secret-key

# Database (if using custom backend)
DATABASE_URL=your-database-url
```

## Timeline
- **Week 1**: Foundation setup
- **Week 2**: Core UI components
- **Week 3**: Mastodon API integration
- **Week 4**: Features & interactions
- **Week 5**: Testing & deployment

## Resources & References
- **GitHub Templates**:
  - https://github.com/harundogdu/twitter-clone
  - https://github.com/ccrsxx/twitter-clone
  - https://github.com/Arsh-pixel-cmd/X-clone-TailwindCss-

- **Documentation**:
  - Mastodon API: https://docs.joinmastodon.org/api/
  - Next.js: https://nextjs.org/docs
  - Tailwind CSS: https://tailwindcss.com/docs

## Next Steps
1. Review and approve this plan
2. Select GitHub template to use
3. Set up development environment
4. Begin Phase 1 implementation