feat: Add SPEC.md for Sozial social media platform

This commit is contained in:
2026-04-29 06:37:09 +02:00
parent 70d812dab8
commit df6cce8678

577
SPEC.md Normal file
View File

@@ -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
```