madgerm/sozial
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
937a32ad06eccf40b6e5a78c6904cfe0634bc0ce
sozial/SPEC.md

16 KiB
Raw Blame History

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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:

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:

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:

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
Reference in New Issue View Git Blame Copy Permalink