diff --git a/SPEC.md b/SPEC.md new file mode 100644 index 0000000..f5c807c --- /dev/null +++ b/SPEC.md @@ -0,0 +1,577 @@ +# 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 +```