Opportunities Service

The Opportunities Service is a comprehensive system for managing job offers, project requests, and collaboration opportunities within the Ring platform. It provides full CRUD operations with advanced filtering, authentication, and internationalization support.

Overview

The opportunities system connects companies, professionals, and projects through a structured marketplace that supports:

Job Opportunities - Full-time and part-time positions
Project Requests - Freelance and contract work
Collaboration Offers - Partnership and joint venture opportunities
Confidential Opportunities - Premium opportunities for verified members
Multi-language Support - Ukrainian and English localization
File Attachments - Supporting documents and portfolios

API Endpoints

Core Opportunity Management

GET /api/opportunities

Retrieve a paginated list of opportunities with filtering and search capabilities.

Query Parameters:

page (number, optional) - Page number for pagination (default: 1)
limit (number, optional) - Items per page (default: 10, max: 50)
category (string, optional) - Filter by opportunity category
type (string, optional) - Filter by opportunity type (job, project, collaboration)
budget_min (number, optional) - Minimum budget filter
budget_max (number, optional) - Maximum budget filter
location (string, optional) - Location filter
remote (boolean, optional) - Remote work filter
search (string, optional) - Search in title and description
entity_id (string, optional) - Filter by posting entity
sort (string, optional) - Sort field (created_at, budget, title)
order (string, optional) - Sort order (asc, desc)

Response:

{
  "opportunities": [
    {
      "id": "opp_123",
      "title": "Senior Full-Stack Developer",
      "description": "We are looking for an experienced full-stack developer...",
      "short_description": "Senior developer position with modern tech stack",
      "category": "Software Development",
      "type": "job",
      "budget": {
        "min": 3000,
        "max": 5000,
        "currency": "USD",
        "per": "month"
      },
      "location": {
        "city": "Kyiv",
        "country": "Ukraine",
        "remote": true
      },
      "requirements": [
        "5+ years of experience",
        "React, Node.js proficiency",
        "English B2+"
      ],
      "benefits": [
        "Flexible schedule",
        "Health insurance",
        "Professional development"
      ],
      "entity": {
        "id": "entity_456",
        "name": "TechCorp Ukraine",
        "logo": "https://storage.com/logos/techcorp.png"
      },
      "attachments": [
        {
          "name": "job_description.pdf",
          "url": "https://storage.com/attachments/job_desc.pdf",
          "size": 245760
        }
      ],
      "application_process": {
        "method": "email",
        "contact": "hr@techcorp.ua",
        "instructions": "Send CV and cover letter"
      },
      "tags": ["react", "nodejs", "typescript", "remote"],
      "status": "active",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-16T14:30:00Z",
      "expires_at": "2024-03-15T23:59:59Z",
      "views": 245,
      "applications": 12
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 15,
    "total_items": 147,
    "per_page": 10,
    "has_next": true,
    "has_prev": false
  },
  "filters": {
    "categories": ["Software Development", "Design", "Marketing"],
    "types": ["job", "project", "collaboration"],
    "locations": ["Kyiv", "Lviv", "Kharkiv", "Remote"]
  }
}

GET /api/opportunities/[id]

Retrieve detailed information about a specific opportunity.

Path Parameters:

id (string, required) - Opportunity identifier

Response:

{
  "opportunity": {
    "id": "opp_123",
    "title": "Senior Full-Stack Developer",
    "description": "Detailed job description with full requirements...",
    "short_description": "Senior developer position with modern tech stack",
    "category": "Software Development",
    "type": "job",
    "budget": {
      "min": 3000,
      "max": 5000,
      "currency": "USD",
      "per": "month"
    },
    "location": {
      "city": "Kyiv",
      "country": "Ukraine",
      "remote": true,
      "timezone": "Europe/Kiev"
    },
    "requirements": [
      "5+ years of full-stack development experience",
      "Expert knowledge of React and Node.js",
      "TypeScript proficiency",
      "English B2+ level"
    ],
    "benefits": [
      "Flexible working hours",
      "Health and dental insurance",
      "Professional development budget",
      "Modern office in city center"
    ],
    "entity": {
      "id": "entity_456",
      "name": "TechCorp Ukraine",
      "logo": "https://storage.com/logos/techcorp.png",
      "website": "https://techcorp.ua",
      "employee_count": "50-100"
    },
    "contact_person": {
      "name": "Anna Kovalenko",
      "position": "HR Manager",
      "email": "anna@techcorp.ua",
      "phone": "+380123456789"
    },
    "application_process": {
      "method": "form",
      "instructions": "Please fill out the application form and attach your CV",
      "required_documents": ["CV", "Cover Letter", "Portfolio"]
    },
    "attachments": [
      {
        "id": "att_789",
        "name": "detailed_job_description.pdf",
        "url": "https://storage.com/attachments/detailed_job.pdf",
        "size": 512000,
        "uploaded_at": "2024-01-15T10:00:00Z"
      }
    ],
    "tags": ["react", "nodejs", "typescript", "remote", "fintech"],
    "status": "active",
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-16T14:30:00Z",
    "expires_at": "2024-03-15T23:59:59Z",
    "views": 245,
    "applications": 12,
    "is_featured": false,
    "visibility": "public"
  }
}

POST /api/opportunities/create

Create a new opportunity. Requires authentication and appropriate permissions.

Authentication: Required (Member role or higher)

Request Body:

{
  "title": "Senior Full-Stack Developer",
  "description": "We are looking for an experienced full-stack developer to join our growing team...",
  "short_description": "Senior developer position with modern tech stack",
  "category": "Software Development",
  "type": "job",
  "budget": {
    "min": 3000,
    "max": 5000,
    "currency": "USD",
    "per": "month"
  },
  "location": {
    "city": "Kyiv",
    "country": "Ukraine",
    "remote": true
  },
  "requirements": [
    "5+ years of experience",
    "React, Node.js proficiency",
    "English B2+"
  ],
  "benefits": [
    "Flexible schedule",
    "Health insurance"
  ],
  "entity_id": "entity_456",
  "contact_person": {
    "name": "Anna Kovalenko",
    "position": "HR Manager",
    "email": "anna@techcorp.ua"
  },
  "application_process": {
    "method": "email",
    "contact": "hr@techcorp.ua",
    "instructions": "Send CV and cover letter"
  },
  "tags": ["react", "nodejs", "typescript"],
  "expires_at": "2024-03-15T23:59:59Z",
  "visibility": "public"
}

Response:

{
  "success": true,
  "opportunity": {
    "id": "opp_new123",
    "title": "Senior Full-Stack Developer",
    "status": "pending",
    "created_at": "2024-01-20T15:30:00Z"
  },
  "message": "Opportunity created successfully and is pending review"
}

PUT /api/opportunities/update

Update an existing opportunity. Requires authentication and ownership/admin permissions.

Authentication: Required (Owner or Admin)

Request Body:

{
  "id": "opp_123",
  "title": "Updated Senior Full-Stack Developer Position",
  "description": "Updated description...",
  "budget": {
    "min": 3500,
    "max": 5500,
    "currency": "USD",
    "per": "month"
  },
  "status": "active",
  "updated_fields": ["title", "description", "budget"]
}

Response:

{
  "success": true,
  "opportunity": {
    "id": "opp_123",
    "updated_at": "2024-01-20T16:45:00Z"
  },
  "message": "Opportunity updated successfully"
}

DELETE /api/opportunities/delete/[id]

Delete an opportunity. Requires authentication and ownership/admin permissions.

Authentication: Required (Owner or Admin)

Path Parameters:

id (string, required) - Opportunity identifier

Response:

{
  "success": true,
  "message": "Opportunity deleted successfully"
}

File Management

POST /api/opportunities/upload

Upload files and attachments for opportunities.

Authentication: Required

Content-Type: multipart/form-data

Form Data:

file (File, required) - File to upload
opportunity_id (string, required) - Opportunity identifier
description (string, optional) - File description

Response:

{
  "success": true,
  "attachment": {
    "id": "att_789",
    "name": "job_requirements.pdf",
    "url": "https://storage.com/attachments/job_req.pdf",
    "size": 245760,
    "uploaded_at": "2024-01-20T17:00:00Z"
  }
}

Premium Content

GET /api/confidential/opportunities

Access confidential opportunities for premium members.

Authentication: Required (Confidential role or higher)

Query Parameters: Same as regular opportunities endpoint

Response: Similar structure to regular opportunities but includes premium content

Frontend Integration

Page Routes

The opportunities system is fully integrated with Next.js 15 App Router:

`/[locale]/opportunities`

Bundle Size: 1.95 kB + 106 kB

Opportunity listing page with filtering and search
Pagination and infinite scroll support
Category-based navigation
Responsive grid layout

`/[locale]/opportunities/[id]`

Bundle Size: 1.95 kB + 106 kB

Detailed opportunity view
Application process integration
Related opportunities suggestions
Social sharing capabilities

`/[locale]/opportunities/add`

Bundle Size: 3.98 kB + 295 kB

Opportunity creation form
Rich text editor for descriptions
File upload interface
Form validation and error handling

`/[locale]/confidential/opportunities`

Bundle Size: 1.26 kB + 112 kB

Premium opportunities for verified members
Enhanced opportunity details
Priority application processing

React Components

Key components for opportunities functionality:

// Opportunity listing component
<OpportunityList 
  opportunities={opportunities}
  filters={filters}
  onFilterChange={handleFilterChange}
  pagination={pagination}
/>

// Opportunity card component
<OpportunityCard 
  opportunity={opportunity}
  showActions={true}
  compact={false}
/>

// Opportunity creation form
<OpportunityForm 
  onSubmit={handleSubmit}
  initialData={initialData}
  entityId={entityId}
/>

// Application process component
<ApplicationProcess 
  opportunity={opportunity}
  user={user}
  onApply={handleApplication}
/>

Service Architecture

Data Models

Opportunity Model:

interface Opportunity {
  id: string
  title: string
  description: string
  short_description?: string
  category: string
  type: 'job' | 'project' | 'collaboration'
  budget?: {
    min?: number
    max?: number
    currency: string
    per: 'hour' | 'day' | 'month' | 'project'
  }
  location: {
    city?: string
    country?: string
    remote: boolean
    timezone?: string
  }
  requirements: string[]
  benefits: string[]
  entity_id: string
  entity?: Entity
  contact_person?: ContactPerson
  application_process: ApplicationProcess  
  attachments: Attachment[]
  tags: string[]
  status: 'draft' | 'pending' | 'active' | 'expired' | 'closed'
  visibility: 'public' | 'members' | 'confidential'
  created_at: string
  updated_at: string
  expires_at?: string
  views: number
  applications: number
  is_featured: boolean
}

Database Operations

The service uses Firebase Firestore with optimized queries:

// Collection reference
const opportunitiesRef = collection(db, 'opportunities')

// Query with filters
const query = query(
  opportunitiesRef,
  where('status', '==', 'active'),
  where('category', 'in', categories),
  orderBy('created_at', 'desc'),
  limit(10)
)

// Real-time subscription
const unsubscribe = onSnapshot(query, (snapshot) => {
  const opportunities = snapshot.docs.map(doc => ({
    id: doc.id,
    ...doc.data()
  }))
})

Authentication & Authorization

Access control is implemented at multiple levels:

Public Access:

View active opportunities
Browse categories and filters
Access opportunity details

Member Access:

Create opportunities (with entity ownership)
Update owned opportunities
Access application tracking

Confidential Access:

View confidential opportunities
Priority placement in listings
Enhanced opportunity analytics

Admin Access:

Moderate all opportunities
Manage opportunity categories
Access comprehensive analytics

Integration Examples

Creating an Opportunity

import { createOpportunity } from '@/lib/opportunities-service'

const handleCreateOpportunity = async (formData: OpportunityFormData) => {
  try {
    const opportunity = await createOpportunity({
      title: formData.title,
      description: formData.description,
      category: formData.category,
      type: formData.type,
      budget: formData.budget,
      location: formData.location,
      requirements: formData.requirements,
      entity_id: userEntity.id,
      expires_at: formData.expiresAt
    })
    
    router.push(`/${locale}/opportunities/${opportunity.id}`)
  } catch (error) {
    toast.error('Failed to create opportunity')
  }
}

Searching Opportunities

import { searchOpportunities } from '@/lib/opportunities-service'

const handleSearch = async (filters: OpportunityFilters) => {
  try {
    const result = await searchOpportunities({
      search: filters.search,
      category: filters.category,
      location: filters.location,
      remote: filters.remote,
      budget_min: filters.budgetMin,
      budget_max: filters.budgetMax,
      page: filters.page,
      limit: 20
    })
    
    setOpportunities(result.opportunities)
    setPagination(result.pagination)
  } catch (error) {
    toast.error('Search failed')
  }
}

Applying to Opportunity

import { applyToOpportunity } from '@/lib/opportunities-service'

const handleApply = async (opportunityId: string, applicationData: ApplicationData) => {
  try {
    await applyToOpportunity(opportunityId, {
      cover_letter: applicationData.coverLetter,
      cv_url: applicationData.cvUrl,
      portfolio_url: applicationData.portfolioUrl,
      availability: applicationData.availability
    })
    
    toast.success('Application submitted successfully')
  } catch (error) {
    toast.error('Failed to submit application')
  }
}

Performance Optimization

Caching Strategy

Client-side caching using React Query for opportunity listings
Server-side caching for frequently accessed opportunities
CDN caching for opportunity attachments and images
Database indexing on commonly filtered fields

Bundle Optimization

The opportunities system is optimized for performance:

Code splitting with dynamic imports for heavy components
Lazy loading for opportunity images and attachments
Pagination to limit data transfer
Optimistic updates for improved user experience

SEO & Internationalization

Localized URLs (/en/opportunities, /uk/opportunities)
Meta tags with opportunity-specific information
Schema.org markup for job posting structured data
Sitemap generation for opportunity pages
Hreflang tags for multilingual SEO

Error Handling

Comprehensive error handling across the service:

// API error responses
{
  "error": true,
  "code": "OPPORTUNITY_NOT_FOUND",
  "message": "The requested opportunity could not be found",
  "details": {
    "opportunity_id": "opp_123",
    "timestamp": "2024-01-20T18:00:00Z"
  }
}

// Common error codes
- OPPORTUNITY_NOT_FOUND
- UNAUTHORIZED_ACCESS
- VALIDATION_ERROR
- ENTITY_REQUIRED
- QUOTA_EXCEEDED
- UPLOAD_FAILED

Monitoring & Analytics

Metrics Tracked

Opportunity views and engagement metrics
Application conversion rates by category
Search performance and popular filters
User interaction patterns and drop-off points
File upload success rates and performance

Performance Monitoring

API response times for all endpoints
Database query performance optimization
Bundle size monitoring for frontend components
Error rate tracking and alerting

The Opportunities Service provides a comprehensive, scalable solution for managing job postings and project opportunities within the Ring platform, with full internationalization support and optimized performance.

Overview​

API Endpoints​

Core Opportunity Management​

GET /api/opportunities​

GET /api/opportunities/[id]​

POST /api/opportunities/create​

PUT /api/opportunities/update​

DELETE /api/opportunities/delete/[id]​

File Management​

POST /api/opportunities/upload​

Premium Content​

GET /api/confidential/opportunities​

Frontend Integration​

Page Routes​

/[locale]/opportunities​

/[locale]/opportunities/[id]​

/[locale]/opportunities/add​

/[locale]/confidential/opportunities​

React Components​

Service Architecture​

Data Models​

Database Operations​

Authentication & Authorization​

Integration Examples​

Creating an Opportunity​

Searching Opportunities​

Applying to Opportunity​

Performance Optimization​

Caching Strategy​

Bundle Optimization​

SEO & Internationalization​

Error Handling​

Monitoring & Analytics​

Metrics Tracked​

Performance Monitoring​

Overview

API Endpoints

Core Opportunity Management

GET /api/opportunities

GET /api/opportunities/[id]

POST /api/opportunities/create

PUT /api/opportunities/update

DELETE /api/opportunities/delete/[id]

File Management

POST /api/opportunities/upload

Premium Content

GET /api/confidential/opportunities

Frontend Integration

Page Routes

`/[locale]/opportunities`

`/[locale]/opportunities/[id]`

`/[locale]/opportunities/add`

`/[locale]/confidential/opportunities`

React Components

Service Architecture

Data Models

Database Operations

Authentication & Authorization

Integration Examples

Creating an Opportunity

Searching Opportunities

Applying to Opportunity

Performance Optimization

Caching Strategy

Bundle Optimization

SEO & Internationalization

Error Handling

Monitoring & Analytics

Metrics Tracked

Performance Monitoring