Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
465 lines (398 loc) · 14.4 KB

ARCHITECTURE.md

File metadata and controls

465 lines (398 loc) · 14.4 KB

Skill Swap Platform - System Architecture

🏗️ Technology Stack

Frontend

  • Framework: React.js with TypeScript
  • State Management: Redux Toolkit / Zustand
  • UI Library: Tailwind CSS + shadcn/ui
  • Real-time: Socket.io-client
  • HTTP Client: Axios

Backend

  • Runtime: Node.js with Express.js
  • Language: TypeScript
  • Authentication: JWT + bcrypt
  • Real-time: Socket.io
  • Validation: Zod / Joi
  • API Style: REST API

Database

  • Primary DB: PostgreSQL (relational data)
  • Cache: Redis (sessions, matching cache)
  • File Storage: AWS S3 (profile images)

AWS Services

  • Compute: AWS EC2 / ECS (Fargate)
  • Database: AWS RDS (PostgreSQL)
  • Cache: AWS ElastiCache (Redis)
  • Storage: AWS S3
  • CDN: AWS CloudFront
  • Load Balancer: AWS ALB
  • Monitoring: AWS CloudWatch
  • Email: AWS SES
  • Optional: AWS Lambda (background jobs)

📊 Database Schema

Users Table

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  full_name VARCHAR(255) NOT NULL,
  bio TEXT,
  profile_image_url VARCHAR(500),
  experience_level VARCHAR(50), -- beginner, intermediate, advanced
  is_active BOOLEAN DEFAULT true,
  is_verified BOOLEAN DEFAULT false,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

Skills Table

CREATE TABLE skills (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(100) UNIQUE NOT NULL,
  category VARCHAR(100), -- tech, design, music, business, etc.
  created_at TIMESTAMP DEFAULT NOW()
);

User_Skills_Offered Table

CREATE TABLE user_skills_offered (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
  skill_id UUID REFERENCES skills(id) ON DELETE CASCADE,
  proficiency_level VARCHAR(50), -- beginner, intermediate, expert
  years_of_experience INT,
  created_at TIMESTAMP DEFAULT NOW(),
  UNIQUE(user_id, skill_id)
);

User_Skills_Wanted Table

CREATE TABLE user_skills_wanted (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
  skill_id UUID REFERENCES skills(id) ON DELETE CASCADE,
  desired_level VARCHAR(50),
  priority VARCHAR(50), -- low, medium, high
  created_at TIMESTAMP DEFAULT NOW(),
  UNIQUE(user_id, skill_id)
);

Availability Table

CREATE TABLE availability (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
  day_of_week INT, -- 0=Sunday, 6=Saturday
  start_time TIME,
  end_time TIME,
  timezone VARCHAR(50),
  created_at TIMESTAMP DEFAULT NOW()
);

Matches Table

CREATE TABLE matches (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user1_id UUID REFERENCES users(id) ON DELETE CASCADE,
  user2_id UUID REFERENCES users(id) ON DELETE CASCADE,
  match_score DECIMAL(5,2), -- compatibility score 0-100
  status VARCHAR(50) DEFAULT 'pending', -- pending, accepted, rejected, completed
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW(),
  UNIQUE(user1_id, user2_id)
);

Swap_Requests Table

CREATE TABLE swap_requests (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  match_id UUID REFERENCES matches(id) ON DELETE CASCADE,
  requester_id UUID REFERENCES users(id),
  receiver_id UUID REFERENCES users(id),
  skill_offered_id UUID REFERENCES skills(id),
  skill_wanted_id UUID REFERENCES skills(id),
  message TEXT,
  status VARCHAR(50) DEFAULT 'pending', -- pending, accepted, rejected, completed, cancelled
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

Messages Table

CREATE TABLE messages (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  sender_id UUID REFERENCES users(id) ON DELETE CASCADE,
  receiver_id UUID REFERENCES users(id) ON DELETE CASCADE,
  match_id UUID REFERENCES matches(id) ON DELETE CASCADE,
  content TEXT NOT NULL,
  is_read BOOLEAN DEFAULT false,
  created_at TIMESTAMP DEFAULT NOW()
);

Reviews Table

CREATE TABLE reviews (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  swap_request_id UUID REFERENCES swap_requests(id) ON DELETE CASCADE,
  reviewer_id UUID REFERENCES users(id),
  reviewee_id UUID REFERENCES users(id),
  rating INT CHECK (rating >= 1 AND rating <= 5),
  comment TEXT,
  created_at TIMESTAMP DEFAULT NOW(),
  UNIQUE(swap_request_id, reviewer_id)
);

Reports Table

CREATE TABLE reports (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  reporter_id UUID REFERENCES users(id),
  reported_user_id UUID REFERENCES users(id),
  reason VARCHAR(255),
  description TEXT,
  status VARCHAR(50) DEFAULT 'pending', -- pending, reviewed, resolved
  created_at TIMESTAMP DEFAULT NOW()
);

🔌 API Endpoints

Authentication

POST   /api/auth/register          - Register new user
POST   /api/auth/login             - Login user
POST   /api/auth/logout            - Logout user
POST   /api/auth/refresh-token     - Refresh JWT token
POST   /api/auth/forgot-password   - Request password reset
POST   /api/auth/reset-password    - Reset password

User Profile

GET    /api/users/me               - Get current user profile
PUT    /api/users/me               - Update current user profile
GET    /api/users/:id              - Get user by ID
POST   /api/users/me/avatar        - Upload profile image
DELETE /api/users/me               - Delete account

Skills

GET    /api/skills                 - Get all skills (with search/filter)
POST   /api/skills                 - Create new skill (admin)
GET    /api/skills/:id             - Get skill by ID

User Skills

POST   /api/users/me/skills/offered    - Add offered skill
DELETE /api/users/me/skills/offered/:id - Remove offered skill
POST   /api/users/me/skills/wanted     - Add wanted skill
DELETE /api/users/me/skills/wanted/:id  - Remove wanted skill
GET    /api/users/:id/skills           - Get user's skills

Availability

GET    /api/users/me/availability      - Get my availability
POST   /api/users/me/availability      - Add availability slot
PUT    /api/users/me/availability/:id  - Update availability
DELETE /api/users/me/availability/:id  - Delete availability

Matching

GET    /api/matches/recommendations    - Get recommended matches
GET    /api/matches                    - Get my matches
GET    /api/matches/:id                - Get match details
POST   /api/matches/search             - Search users by skills

Swap Requests

POST   /api/swap-requests              - Create swap request
GET    /api/swap-requests              - Get my swap requests
GET    /api/swap-requests/:id          - Get swap request details
PUT    /api/swap-requests/:id/accept   - Accept swap request
PUT    /api/swap-requests/:id/reject   - Reject swap request
PUT    /api/swap-requests/:id/complete - Mark as completed
DELETE /api/swap-requests/:id          - Cancel swap request

Messaging

GET    /api/messages/conversations     - Get all conversations
GET    /api/messages/:matchId          - Get messages for a match
POST   /api/messages                   - Send message
PUT    /api/messages/:id/read          - Mark message as read

Reviews

POST   /api/reviews                    - Create review
GET    /api/reviews/user/:userId       - Get reviews for a user
GET    /api/reviews/:id                - Get review by ID

Reports

POST   /api/reports                    - Report a user
GET    /api/reports                    - Get all reports (admin)
PUT    /api/reports/:id                - Update report status (admin)

Admin

GET    /api/admin/users                - Get all users
PUT    /api/admin/users/:id/ban        - Ban user
PUT    /api/admin/users/:id/unban      - Unban user
GET    /api/admin/stats                - Get platform statistics

🎯 Matching Algorithm Logic

Match Score Calculation

function calculateMatchScore(user1, user2) {
  let score = 0;
  
  // 1. Skill Compatibility (60 points)
  const user1Offers = user1.skillsOffered;
  const user2Wants = user2.skillsWanted;
  const user2Offers = user2.skillsOffered;
  const user1Wants = user1.skillsWanted;
  
  const matchingSkills1 = intersection(user1Offers, user2Wants);
  const matchingSkills2 = intersection(user2Offers, user1Wants);
  
  score += (matchingSkills1.length + matchingSkills2.length) * 15;
  
  // 2. Availability Overlap (20 points)
  const availabilityOverlap = calculateTimeOverlap(user1.availability, user2.availability);
  score += availabilityOverlap * 20;
  
  // 3. Experience Level Match (10 points)
  if (isExperienceLevelCompatible(user1, user2)) {
    score += 10;
  }
  
  // 4. User Ratings (10 points)
  const avgRating = (user1.rating + user2.rating) / 2;
  score += (avgRating / 5) * 10;
  
  return Math.min(score, 100);
}

🏛️ System Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                        AWS CloudFront (CDN)                  │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────────┐
│                   AWS Application Load Balancer              │
└────────────┬───────────────────────────────┬────────────────┘
             │                               │
    ┌────────┴────────┐            ┌────────┴────────┐
    │   Frontend      │            │   Backend       │
    │   (React App)   │            │   (Node.js)     │
    │   S3 + CF       │            │   ECS/EC2       │
    └─────────────────┘            └────────┬────────┘
                                            │
                    ┌───────────────────────┼───────────────────┐
                    │                       │                   │
          ┌─────────┴─────────┐   ┌────────┴────────┐  ┌──────┴──────┐
          │   PostgreSQL      │   │     Redis       │  │   AWS S3    │
          │   (AWS RDS)       │   │ (ElastiCache)   │  │  (Storage)  │
          └───────────────────┘   └─────────────────┘  └─────────────┘

🚀 MVP Roadmap

Phase 1: Core MVP (4-6 weeks)

Week 1-2: Foundation

  • Setup project structure (frontend + backend)
  • Database schema implementation
  • User authentication (register, login, JWT)
  • Basic user profile CRUD

Week 3-4: Skills & Matching

  • Skills management (add/remove offered/wanted skills)
  • Basic matching algorithm
  • Search and filter users by skills
  • Match recommendations page

Week 5-6: Communication & Swaps

  • Swap request system (create, accept, reject)
  • Basic in-app messaging
  • User dashboard
  • Deploy MVP to AWS

Phase 2: Enhanced Features (4-6 weeks)

Week 7-8: Trust & Reputation

  • Reviews and ratings system
  • User reputation score
  • Completed swaps history
  • Profile verification

Week 9-10: Advanced Features

  • Real-time chat with Socket.io
  • Availability calendar integration
  • Email notifications (AWS SES)
  • Advanced matching filters

Week 11-12: Admin & Polish

  • Admin panel
  • User reporting system
  • Platform analytics
  • UI/UX improvements

Phase 3: Scale & Optimize (Ongoing)

  • Performance optimization
  • Caching strategy with Redis
  • CDN setup for static assets
  • Mobile responsive design
  • SEO optimization
  • A/B testing for matching algorithm

🔒 Security Considerations

  1. Authentication: JWT with refresh tokens, httpOnly cookies
  2. Password: bcrypt hashing (salt rounds: 12)
  3. Input Validation: Zod/Joi schemas on all endpoints
  4. Rate Limiting: Express-rate-limit middleware
  5. CORS: Whitelist frontend domain only
  6. SQL Injection: Use parameterized queries (Prisma/TypeORM)
  7. XSS Protection: Sanitize user inputs
  8. File Upload: Validate file types, size limits on S3
  9. Environment Variables: AWS Secrets Manager

📦 Project Structure

skill-swap/
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── hooks/
│   │   ├── services/
│   │   ├── store/
│   │   ├── types/
│   │   └── utils/
│   ├── public/
│   └── package.json
│
├── backend/
│   ├── src/
│   │   ├── controllers/
│   │   ├── routes/
│   │   ├── models/
│   │   ├── middleware/
│   │   ├── services/
│   │   ├── utils/
│   │   ├── config/
│   │   └── server.ts
│   ├── prisma/
│   │   └── schema.prisma
│   └── package.json
│
├── infrastructure/
│   ├── terraform/
│   └── docker/
│
└── README.md

💰 Estimated AWS Costs (Monthly - MVP)

  • EC2 (t3.medium): ~$30
  • RDS PostgreSQL (db.t3.micro): ~$15
  • ElastiCache Redis (cache.t3.micro): ~$12
  • S3 Storage (50GB): ~$1
  • CloudFront: ~$5
  • ALB: ~$20
  • SES (Email): ~$1

Total: ~$85/month for MVP

🎯 Key Success Metrics

  1. User Engagement: Active users, daily logins
  2. Match Quality: Successful swap completion rate
  3. User Satisfaction: Average rating, reviews
  4. Platform Growth: New signups, retention rate
  5. Communication: Messages sent, response time

This architecture is production-ready, scalable, and optimized for AWS deployment!