Backend API OverviewCopy Anchor Link

A robust Express.js backend service providing feedback management, user authentication, analytics tracking, and admin capabilities for the portfolio ecosystem.

🚀 Quick LinksCopy Anchor Link

API Base URL: http://localhost:3001 (development)
Repository: GitHub
Status Endpoint: /health

✨ Key FeaturesCopy Anchor Link

Authentication & AuthorizationCopy Anchor Link

• Supabase Auth Integration - Sign up, sign in, password reset
• JWT Token Management - Secure session handling
• Role-Based Access Control - Admin, editor, viewer roles
• Legacy Admin Tokens - Backward compatibility support

Feedback SystemCopy Anchor Link

• Public Submissions - Anyone can submit feedback
• Admin Management - View, update, and resolve feedback
• Status Tracking - Pending, resolved, archived states
• Rich Metadata - Location, category, screenshots

Analytics & TrackingCopy Anchor Link

• Website Analytics - Page views, sessions, events
• Date Range Queries - Historical data analysis
• Real-time Metrics - Current activity monitoring
• Custom Event Tracking - Application-specific events

Admin CapabilitiesCopy Anchor Link

• Health Monitoring - System, database, email status
• Metrics Dashboard - Request statistics and summaries
• Log Management - Structured logging with filtering
• User Management - CRUD operations for users

🛠️ Tech StackCopy Anchor Link

📊 API ArchitectureCopy Anchor Link

graph TD
    A[Client] -->|HTTP Request| B[Express Server]
    B --> C{Route Handler}
    C -->|Auth| D[Supabase Auth]
    C -->|Feedback| E[Feedback Service]
    C -->|Analytics| F[Analytics Service]
    C -->|Admin| G[Admin Service]
    
    D --> H[(Supabase DB)]
    E --> H
    F --> H
    G --> H
    
    E -->|Notifications| I[Email Service]
    I -->|SMTP| J[Nodemailer]
    I -->|API| K[Resend]
    
    G -->|Monitoring| L[Winston Logger]
    L --> M[Log Files]

🔐 Authentication FlowCopy Anchor Link

sequenceDiagram
    participant Client
    participant API
    participant Supabase
    participant Database

    Client->>API: POST /api/auth/signup
    API->>Supabase: Create user
    Supabase->>Database: Insert auth.users
    Database-->>Database: Trigger sync to public.users
    Database-->>Supabase: User created
    Supabase-->>API: Session tokens
    API-->>Client: Access + Refresh tokens

    Client->>API: GET /api/users/me (with token)
    API->>Supabase: Verify token
    Supabase-->>API: User data
    API-->>Client: User profile

📡 API Endpoints OverviewCopy Anchor Link

Authentication Routes (/api/auth)Copy Anchor Link

• POST /signup - Register new user
• POST /signin - Sign in with credentials
• POST /signout - End user session
• POST /reset-password - Request password reset
• POST /update-password - Update password with token
• GET /me - Get current user profile
• POST /link - Link social accounts

Feedback Routes (/api/feedback)Copy Anchor Link

• POST / - Submit feedback (public)
• GET /get-feedback - Retrieve all feedback (admin)
• POST /submit-feedback - Legacy submission endpoint

Analytics Routes (/api/analytics)Copy Anchor Link

• GET / - Get all analytics entries
• GET /website/:websiteId - Get analytics by website
• GET /date-range - Query by date range
• POST / - Create analytics entry

Admin Routes (/api/admin)Copy Anchor Link

• GET /health - System health check
• GET /metrics - Request metrics
• GET /logs - Retrieve logs
• POST /logs - Add log entry
• GET /users - List all users

User Routes (/api/users)Copy Anchor Link

• GET /:id - Get user by ID
• GET /email/:email - Get user by email
• POST / - Create user
• PUT /:id - Update user

Website Routes (/api/websites)Copy Anchor Link

• GET / - List all websites
• GET /:id - Get website by ID
• GET /api-key/:apiKey - Get by API key
• POST / - Create website
• PUT /:id - Update website
• DELETE /:id - Delete website

User Roles Routes (/api/userRoles)Copy Anchor Link

• GET /:userId - Get user roles
• POST /:userId - Assign roles

🔒 Security FeaturesCopy Anchor Link

Input ValidationCopy Anchor Link

All endpoints use Zod schema validation:

const feedbackSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
  comment: z.string().min(10),
  rating: z.number().int().min(1).max(5),
});

Rate LimitingCopy Anchor Link

Protection against abuse:

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // Limit each IP to 100 requests per window
});

Bot ProtectionCopy Anchor Link

Middleware to detect and block bots:

app.use('/api/feedback', botProtectionMiddleware);

CORS ConfigurationCopy Anchor Link

Controlled cross-origin access:

app.use(cors({
  origin: process.env.FRONTEND_URL,
  credentials: true,
}));

📊 Database SchemaCopy Anchor Link

Key TablesCopy Anchor Link

users - User accounts

• Synced from auth.users via trigger
• Stores profile information
• Tracks last login

feedback - Feedback submissions

• Status tracking (pending/resolved/archived)
• Rich metadata (location, category, screenshot)
• Admin notes and resolution tracking

analytics - Website analytics

• Event tracking
• Session data
• Performance metrics

websites - Website configurations

• API key management
• Settings and metadata

user_roles - Role assignments

• Admin, editor, viewer roles
• Permission management

⚡ Performance FeaturesCopy Anchor Link

CachingCopy Anchor Link

Redis integration for frequently accessed data:

const cached = await redis.get(`github-stats`);
if (cached) return JSON.parse(cached);

Connection PoolingCopy Anchor Link

Efficient database connections with Supabase client.

Response CompressionCopy Anchor Link

Automatic gzip compression for responses.

📝 LoggingCopy Anchor Link

Structured logging with Winston:

logger.info('Feedback submitted', {
  feedbackId: feedback.id,
  userEmail: feedback.email,
  timestamp: new Date().toISOString(),
});

Log levels: error, warn, info, http, debug

🔍 MonitoringCopy Anchor Link

Health CheckCopy Anchor Link

curl http://localhost:3001/health

Response:

{
  "status": "ok",
  "timestamp": "2025-12-18T10:00:00.000Z"
}

Status DashboardCopy Anchor Link

Access at: /admin/status (admin only)

Features:

• Real-time metrics
• Request statistics
• Memory usage
• Response times

🚀 Getting StartedCopy Anchor Link

InstallationCopy Anchor Link

cd Backend
pnpm install

ConfigurationCopy Anchor Link

Create .env file:

PORT=3001
FRONTEND_URL=http://localhost:3000

SUPABASE_URL=https://xxx.supabase.co
SUPABASE_ANON_KEY=xxx
SUPABASE_SERVICE_ROLE_KEY=xxx

ADMIN_TOKEN_SECRET=your-secret-key

EMAIL_PROVIDER=nodemailer
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password

Start ServerCopy Anchor Link

# Development
pnpm dev

# Production
pnpm build
pnpm start

📚 Detailed DocumentationCopy Anchor Link

• Authentication - User auth and JWT tokens
• Feedback API - Feedback management
• Analytics API - Analytics tracking
• Admin API - Admin operations
• Setup Guide - Complete setup instructions
• Error Handling - Error responses

🔗 Related ResourcesCopy Anchor Link

• Portfolio Frontend
• API Testing
• Deployment Guide

Built with Express.js and Supabase