sozial/SPEC.md

# Sozial - Social Media & Casual Dating Platform

## 1. Concept & Vision

**Sozial** ist eine moderne Social-Media-Plattform für Casual Dating und Community-Meetups. Die Plattform kombiniert die soziale Interaktion klassischer sozialer Netzwerke mit einer lockeren, einladenden Atmosphäre für ungezwungene Begegnungen. Das Ziel: Menschen zusammenbringen, die sich persönlich treffen wollen – ob für ein Café, einen Spaziergang oder einfach ein Gespräch.

Das Erlebnis soll sich anfühlen wie ein guter Abend in einer Bar – unkompliziert, offen und natürlich.

## 2. Design Language

### Aesthetic Direction
Inspiriert von modernen Dating-Apps (Tinder, Bumble) kombiniert mit der Funktionalität von Social Networks (Facebook, Instagram). Warme, einladende Farben mit sanften Gradienten und abgerundeten Formen.

### Color Palette
```
Primary:        #6366F1 (Indigo - Vertrauen & Modernität)
Secondary:      #EC4899 (Pink - Romantik & Energie)
Accent:         #F59E0B (Amber - Wärme & Einladung)
Background:     #FAFAFA (Hellgrau)
Surface:        #FFFFFF (Weiß)
Text Primary:  #1F2937 (Dunkelgrau)
Text Secondary: #6B7280 (Mittelgrau)
Success:       #10B981 (Grün)
Error:         #EF4444 (Rot)
Online:        #22C55E (Grün - für Online-Status)
```

### Typography
- **Headlines:** Inter, 700 weight
- **Body:** Inter, 400/500 weight
- **Monospace:** JetBrains Mono (für Code/Tags)
- Font sizes: 12px, 14px, 16px, 20px, 24px, 32px, 48px

### Spatial System
- Base unit: 4px
- Spacing scale: 4, 8, 12, 16, 24, 32, 48, 64, 96
- Border radius: 8px (small), 12px (medium), 16px (large), 9999px (pill)
- Card shadows: `0 2px 8px rgba(0,0,0,0.08)`

### Motion Philosophy
- Micro-interactions: 150ms ease-out
- Page transitions: 300ms ease-in-out
- Loading states: Skeleton screens mit shimmer
- Haptic feedback bei Interaktionen (wo unterstützt)

## 3. Layout & Structure

### Page Architecture

```
┌─────────────────────────────────────────────────────┐
│  Header (Sticky)                                     │
│  [Logo] [Search] [Nav: Feed|Explore|Messages] [⚙️] │
├─────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌────────────────────┐  ┌──────────┐│
│  │ Sidebar │  │ Main Content        │  │ Right    ││
│  │          │  │                    │  │ Sidebar  ││
│  │ Profile  │  │ (Feed/Profile/     │  │          ││
│  │ Quick    │  │  Messages/         │  │ Friend   ││
│  │ Actions  │  │  Settings)         │  │ Requests ││
│  │          │  │                    │  │ Trends   ││
│  └──────────┘  └────────────────────┘  └──────────┘│
└─────────────────────────────────────────────────────┘
```

### Responsive Strategy
- **Desktop (1200px+):** 3-column layout
- **Tablet (768px-1199px):** 2-column, collapsible sidebar
- **Mobile (<768px):** Single column, bottom navigation

### Subdomain Structure
```
www.sozial.shadow-land.de   → Frontend (Public pages, landing)
api.sozial.shadow-land.de   → REST API
chat.sozial.shadow-land.de  → WebSocket Chat Server
```

## 4. Features & Interactions

### 4.1 User Authentication

**Registration:**
- Email + Password
- OAuth (Google, Apple) - optional
- Email verification required
- Onboarding flow: Profile photo, bio, interests

**Login:**
- Email + Password
- "Remember me" functionality
- Password reset via email

**Session:**
- JWT tokens (access + refresh)
- 24h access token, 30d refresh token
- Automatic refresh

### 4.2 User Profiles

**Profile Data:**
```json
{
  "id": "uuid",
  "username": "string (unique)",
  "display_name": "string",
  "bio": "string (max 500 chars)",
  "avatar_url": "string",
  "photos": ["url1", "url2", "url3", "url4", "url5", "url6"],
  "gender": "string",
  "interested_in": ["men", "women", "all"],
  "age": "number",
  "location": {
    "city": "string",
    "lat": "number",
    "lng": "number"
  },
  "interests": ["tag1", "tag2", "..."],
  "is_online": "boolean",
  "last_seen": "timestamp",
  "created_at": "timestamp",
  "settings": {
    "show_online_status": "boolean",
    "show_distance": "boolean",
    "show_age": "boolean",
    "receive_messages_from": "everyone|friends|all"
  }
}
```

**Profile States:**
- Default view (limited info for non-friends)
- Full profile (for friends)
- Own profile (with edit functionality)
- Preview mode (how others see you)

### 4.3 Social Feed

**Post Types:**
- Text post (max 2000 chars)
- Image post (1-4 images)
- Location check-in

**Post Structure:**
```json
{
  "id": "uuid",
  "author_id": "uuid",
  "type": "text|image|checkin",
  "content": "string",
  "media_urls": ["url1", "..."],
  "location": { "name": "string", "lat": "num", "lng": "num" },
  "likes_count": "number",
  "comments_count": "number",
  "shares_count": "number",
  "liked_by_me": "boolean",
  "created_at": "timestamp"
}
```

**Interactions:**
- Like (toggle heart icon, +1 animation)
- Comment (expandable section)
- Share (copy link)
- Save (bookmark for later)
- Report (modal with reason selection)

**Feed Algorithm:**
- Chronological by default
- "For You" tab with algorithmic ranking
- Filter by: All | Friends | Nearby | Interests

### 4.4 Friend & Follow System

**Connection Types:**
- **Friends:** Mutual follow, can see full profile + message
- **Following:** One-way follow, limited profile access
- **Followers:** People following you

**Actions:**
- Follow / Unfollow
- Add Friend / Remove Friend
- Block / Report

**Friend Requests:**
- Pending requests badge
- Accept / Decline
- "Suggest Friends" based on mutual connections

### 4.5 Direct Messaging

**Features:**
- 1:1 private messages
- Text + emoji support
- Read receipts (optional setting)
- Typing indicators
- Online/Offline status
- Message search

**Message Structure:**
```json
{
  "id": "uuid",
  "conversation_id": "uuid",
  "sender_id": "uuid",
  "content": "string",
  "type": "text|image",
  "media_url": "string|null",
  "read_at": "timestamp|null",
  "created_at": "timestamp"
}
```

**Conversation:**
```json
{
  "id": "uuid",
  "type": "direct|group",
  "name": "string (for groups)",
  "participants": ["user_id1", "user_id2"],
  "last_message": { "...message object" },
  "updated_at": "timestamp"
}
```

### 4.6 Discovery & Search

**Search:**
- User search by username/name
- Filter by: location, age, interests, online status
- Recent searches
- Suggested users

**Explore Tab:**
- Featured profiles
- Nearby users (distance-based)
- Users with similar interests
- "Recently active" section

**Discovery Cards:**
- Swipe-style cards (optional toggle)
- Like / Pass / Super Like
- Match notification when mutual like

### 4.7 Real-time Notifications

**Notification Types:**
- New friend request
- Friend request accepted
- New follower
- Post liked
- Post commented
- Message received
- Profile viewed (optional, premium)

**Delivery:**
- Real-time via WebSocket
- Fallback polling every 30s
- Push notifications (PWA + Mobile)

### 4.8 Privacy & Safety

**Privacy Controls:**
- Profile visibility: Public | Friends Only | Private
- Online status visibility
- Read receipts toggle
- Block list management
- Two-factor authentication (optional)

**Safety Features:**
- Report user/post
- Block user (hides from both sides)
- Content moderation (reported content reviewed)
- Age verification (18+)
- Anti-catfishing: Photo verification (future)

## 5. Component Inventory

### 5.1 Navigation
- **TopNav:** Logo, search input, nav links, user menu
  - States: default, search-focused, user-menu-open
- **BottomNav (mobile):** Home, Search, Create (+), Messages, Profile
  - States: default, active tab highlighted

### 5.2 Cards
- **UserCard:** Avatar, name, bio preview, age, distance, interests, action buttons
  - States: default, hover (shadow increase), loading (skeleton)
- **PostCard:** Author header, content, media, action bar, comments preview
  - States: default, expanded (showing comments), loading
- **MatchCard:** Two user avatars, "It's a Match!" banner, action buttons
  - States: default, new-match (with animation)

### 5.3 Forms
- **Input:** Label, input field, helper text, error message
  - States: default, focused, filled, error, disabled
- **TextArea:** Multi-line input with character count
  - States: same as Input
- **Select/Dropdown:** Custom styled select
  - States: default, open, selected, disabled
- **Button:** Primary, Secondary, Ghost, Danger variants
  - States: default, hover, active, loading, disabled
- **Checkbox/Radio:** Custom styled with labels
  - States: unchecked, checked, disabled

### 5.4 Feedback
- **Toast:** Success, Error, Warning, Info variants
  - Auto-dismiss after 4s, manual dismiss available
- **Modal:** Centered overlay with header, content, actions
  - States: entering (fade+scale), visible, exiting
- **Skeleton:** Placeholder shimmer for loading states
- **Spinner:** Circular loading indicator
- **EmptyState:** Illustration + text + action button

### 5.5 Media
- **Avatar:** Circular image with fallback initials
  - Sizes: sm (32px), md (48px), lg (64px), xl (128px)
  - States: image, loading, error (shows initials)
- **ImageGrid:** 1-4 images in responsive grid
  - Lightbox on click
- **VideoPlayer:** Custom controls, autoplay mute on scroll

### 5.6 Chat
- **MessageBubble:** Text content, timestamp, read receipt
  - Variants: sent (right, primary color), received (left, gray)
- **ChatListItem:** Avatar, name, last message preview, timestamp, unread badge
  - States: default, unread (bold), selected
- **TypingIndicator:** Three bouncing dots animation

## 6. Technical Approach

### 6.1 Tech Stack

**Frontend:**
- React 18 + TypeScript
- Vite (build tool)
- Tailwind CSS (styling)
- React Router v6 (routing)
- TanStack Query (server state)
- Zustand (client state)
- Socket.io-client (real-time)

**Backend:**
- PHP 8.2+ (Laravel-like structure)
- SQLite database (per-user isolation via separate DBs)
- JWT Authentication (firebase/php-jwt)
- RESTful API
- Socket.io for WebSocket (PHP with Swoole/Ratchet)

**Infrastructure:**
- Caddy webserver
- PHP-FPM
- WebSocket server on separate port
- S3-compatible storage for media (MinIO or local)

### 6.2 API Design

**Base URL:** `https://api.sozial.shadow-land.de/v1`

**Authentication:**
```
POST   /auth/register
POST   /auth/login
POST   /auth/refresh
POST   /auth/logout
```

**Users:**
```
GET    /users/:id
PATCH  /users/:id
DELETE /users/:id
GET    /users/search?q=query&filters=...
GET    /users/:id/posts
GET    /users/:id/friends
GET    /users/:id/followers
GET    /users/:id/following
```

**Posts:**
```
GET    /posts
POST   /posts
GET    /posts/:id
PATCH  /posts/:id
DELETE /posts/:id
POST   /posts/:id/like
DELETE /posts/:id/like
GET    /posts/:id/comments
POST   /posts/:id/comments
```

**Relationships:**
```
POST   /relationships/follow/:userId
DELETE /relationships/follow/:userId
POST   /relationships/friend-request/:userId
POST   /relationships/accept-friend/:userId
DELETE /relationships/reject-friend/:userId
GET    /relationships/friends
GET    /relationships/requests
```

**Messages:**
```
GET    /conversations
GET    /conversations/:id/messages
POST   /conversations/:id/messages
PATCH  /messages/:id/read
```

**Media:**
```
POST   /media/upload
DELETE /media/:id
```

### 6.3 Data Model

**Users Table:**
```sql
CREATE TABLE users (
  id TEXT PRIMARY KEY,
  email TEXT UNIQUE NOT NULL,
  password_hash TEXT NOT NULL,
  username TEXT UNIQUE NOT NULL,
  display_name TEXT,
  bio TEXT,
  avatar_url TEXT,
  photos TEXT, -- JSON array
  gender TEXT,
  interested_in TEXT, -- JSON array
  age INTEGER,
  location TEXT, -- JSON object
  interests TEXT, -- JSON array
  is_online INTEGER DEFAULT 0,
  last_seen INTEGER,
  settings TEXT, -- JSON object
  created_at INTEGER,
  updated_at INTEGER
);
```

**Posts Table:**
```sql
CREATE TABLE posts (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  type TEXT NOT NULL, -- text|image|checkin
  content TEXT,
  media_urls TEXT, -- JSON array
  location TEXT, -- JSON object
  created_at INTEGER,
  FOREIGN KEY (user_id) REFERENCES users(id)
);
```

**Relationships Table:**
```sql
CREATE TABLE relationships (
  id TEXT PRIMARY KEY,
  follower_id TEXT NOT NULL,
  following_id TEXT NOT NULL,
  type TEXT NOT NULL, -- follow|friend
  status TEXT DEFAULT 'active', -- active|blocked
  created_at INTEGER,
  FOREIGN KEY (follower_id) REFERENCES users(id),
  FOREIGN KEY (following_id) REFERENCES users(id)
);
```

**Messages Table:**
```sql
CREATE TABLE messages (
  id TEXT PRIMARY KEY,
  conversation_id TEXT NOT NULL,
  sender_id TEXT NOT NULL,
  content TEXT NOT NULL,
  type TEXT DEFAULT 'text',
  media_url TEXT,
  read_at INTEGER,
  created_at INTEGER,
  FOREIGN KEY (conversation_id) REFERENCES conversations(id),
  FOREIGN KEY (sender_id) REFERENCES users(id)
);
```

### 6.4 WebSocket Events

**Client → Server:**
- `join_conversation` { conversationId }
- `leave_conversation` { conversationId }
- `send_message` { conversationId, content, type }
- `typing_start` { conversationId }
- `typing_stop` { conversationId }

**Server → Client:**
- `new_message` { message }
- `user_typing` { conversationId, userId }
- `user_online` { userId }
- `user_offline` { userId }
- `notification` { type, data }

### 6.5 Security Considerations

- All passwords hashed with bcrypt (cost factor 12)
- JWT signed with HS256, secret from environment
- CSRF protection via tokens
- Rate limiting on auth endpoints (5/min)
- Input sanitization and validation
- SQL injection prevention via prepared statements
- XSS prevention via output encoding
- File upload validation (type, size, malware scan)
- Secure headers (CSP, HSTS, X-Frame-Options)

## 7. Development Phases

### Phase 1: Foundation
- [ ] Project setup (repository, environments)
- [ ] Authentication system
- [ ] Basic user profiles
- [ ] Database schema

### Phase 2: Social Core
- [ ] Post creation & feed
- [ ] Like & comment system
- [ ] Friend/Follow system
- [ ] User search & discovery

### Phase 3: Messaging
- [ ] Conversation system
- [ ] Direct messaging
- [ ] Real-time updates (WebSocket)
- [ ] Typing indicators

### Phase 4: Polish
- [ ] Notifications
- [ ] Privacy settings
- [ ] Profile customization
- [ ] Media uploads

### Phase 5: Discovery (Future)
- [ ] Match algorithm
- [ ] Location-based discovery
- [ ] Advanced filtering
- [ ] Premium features

## 8. File Structure

```
sozial/
├── www/
│   └── public/
│       └── index.php          # Frontend entry
├── api/
│   └── public/
│       └── index.php          # API entry
├── chat/
│   └── public/
│       └── index.php          # WebSocket entry
├── src/
│   ├── core/                  # Framework core
│   ├── modules/              # Feature modules
│   │   ├── auth/
│   │   ├── user/
│   │   ├── post/
│   │   ├── message/
│   │   └── relationship/
│   ├── services/             # Business logic
│   ├── utils/                # Helpers
│   └── config/               # Configuration
├── database/
│   └── schema.sql            # Database schema
├── tests/
│   └── unit/
├── SPEC.md
├── README.md
└── .env.example
```