Entity Management Service

The Entity Management Service provides comprehensive functionality for managing company and organization profiles within the Ring platform. It supports full CRUD operations, file uploads, role-based access control, and internationalization.

Overview

The entity system enables organizations to:

Create Company Profiles - Showcase organization information and capabilities
Manage Rich Media - Upload logos, images, and portfolio documents
Control Visibility - Public, member-only, and confidential entity access
Category Management - Organize entities by technology focus and industry
Search & Discovery - Advanced filtering and search capabilities
Multi-language Support - Ukrainian and English localization

API Endpoints

Core Entity Management

GET /api/entities

Retrieve a paginated list of entities 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 entity category
location (string, optional) - Filter by location
size (string, optional) - Filter by company size (startup, small, medium, large)
search (string, optional) - Search in name and description
sort (string, optional) - Sort field (name, created_at, employee_count)
order (string, optional) - Sort order (asc, desc)
visibility (string, optional) - Filter by visibility level

Response:

{
  "entities": [
    {
      "id": "entity_123",
      "name": "TechCorp Ukraine",
      "description": "Leading software development company specializing in fintech solutions",
      "short_description": "Fintech software development",
      "category": "Software Development",
      "subcategory": "Financial Technology",
      "logo": "https://storage.com/logos/techcorp.png",
      "website": "https://techcorp.ua",
      "location": {
        "city": "Kyiv",
        "country": "Ukraine",
        "address": "123 Innovation Street"
      },
      "contact": {
        "email": "info@techcorp.ua",
        "phone": "+380123456789",
        "linkedin": "https://linkedin.com/company/techcorp"
      },
      "size": "medium",
      "employee_count": "50-100",
      "founded_year": 2018,
      "visibility": "public",
      "is_confidential": false,
      "tags": ["fintech", "blockchain", "mobile apps"],
      "portfolio": [
        {
          "title": "Banking Mobile App",
          "description": "Full-featured banking application",
          "image": "https://storage.com/portfolio/banking-app.png",
          "url": "https://demo.bankingapp.com"
        }
      ],
      "created_at": "2024-01-10T09:00:00Z",
      "updated_at": "2024-01-15T14:30:00Z",
      "created_by": "user_456"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 8,
    "total_items": 76,
    "per_page": 10,
    "has_next": true,
    "has_prev": false
  },
  "filters": {
    "categories": ["Software Development", "Design", "Marketing", "Consulting"],
    "locations": ["Kyiv", "Lviv", "Kharkiv", "Odesa"],
    "sizes": ["startup", "small", "medium", "large"]
  }
}

GET /api/entities/[id]

Retrieve detailed information about a specific entity.

Path Parameters:

id (string, required) - Entity identifier

Response:

{
  "entity": {
    "id": "entity_123",
    "name": "TechCorp Ukraine",
    "description": "TechCorp Ukraine is a leading software development company...",
    "short_description": "Fintech software development",
    "category": "Software Development",
    "subcategory": "Financial Technology",
    "logo": "https://storage.com/logos/techcorp.png",
    "images": [
      "https://storage.com/images/office1.jpg",
      "https://storage.com/images/team.jpg"
    ],
    "website": "https://techcorp.ua",
    "location": {
      "city": "Kyiv",
      "country": "Ukraine",
      "address": "123 Innovation Street",
      "postal_code": "01001",
      "timezone": "Europe/Kiev"
    },
    "contact": {
      "email": "info@techcorp.ua",
      "phone": "+380123456789",
      "linkedin": "https://linkedin.com/company/techcorp",
      "twitter": "https://twitter.com/techcorp",
      "facebook": "https://facebook.com/techcorp"
    },
    "size": "medium",
    "employee_count": "50-100",
    "founded_year": 2018,
    "visibility": "public",
    "is_confidential": false,
    "tags": ["fintech", "blockchain", "mobile apps", "web development"],
    "services": [
      "Custom Software Development",
      "Mobile App Development",
      "Blockchain Solutions",
      "Consulting Services"
    ],
    "technologies": [
      "React", "Node.js", "Python", "Go", "PostgreSQL", "AWS"
    ],
    "portfolio": [
      {
        "id": "portfolio_1",
        "title": "Banking Mobile App",
        "description": "Full-featured banking application with advanced security",
        "image": "https://storage.com/portfolio/banking-app.png",
        "url": "https://demo.bankingapp.com",
        "technologies": ["React Native", "Node.js", "PostgreSQL"],
        "completed_date": "2023-12-01"
      }
    ],
    "certifications": [
      {
        "name": "ISO 27001",
        "issuer": "International Organization for Standardization",
        "issued_date": "2023-06-01",
        "expires_date": "2026-06-01"
      }
    ],
    "achievements": [
      "Best Fintech Startup 2023",
      "Top 10 Software Companies in Ukraine"
    ],
    "opportunities_count": 5,
    "created_at": "2024-01-10T09:00:00Z",
    "updated_at": "2024-01-15T14:30:00Z",
    "created_by": "user_456"
  }
}

POST /api/entities/create

Create a new entity. Requires authentication and appropriate permissions.

Authentication: Required (Member role or higher)

Request Body:

{
  "name": "TechCorp Ukraine",
  "description": "Leading software development company...",
  "short_description": "Fintech software development",
  "category": "Software Development",
  "subcategory": "Financial Technology",
  "website": "https://techcorp.ua",
  "location": {
    "city": "Kyiv",
    "country": "Ukraine",
    "address": "123 Innovation Street"
  },
  "contact": {
    "email": "info@techcorp.ua",
    "phone": "+380123456789",
    "linkedin": "https://linkedin.com/company/techcorp"
  },
  "size": "medium",
  "employee_count": "50-100",
  "founded_year": 2018,
  "visibility": "public",
  "tags": ["fintech", "blockchain", "mobile apps"],
  "services": [
    "Custom Software Development",
    "Mobile App Development"
  ],
  "technologies": ["React", "Node.js", "Python"]
}

Response:

{
  "success": true,
  "entity": {
    "id": "entity_new123",
    "name": "TechCorp Ukraine",
    "status": "pending",
    "created_at": "2024-01-20T15:30:00Z"
  },
  "message": "Entity created successfully and is pending review"
}

PUT /api/entities/update/[id]

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

Authentication: Required (Owner or Admin)

Path Parameters:

id (string, required) - Entity identifier

Request Body:

{
  "name": "Updated TechCorp Ukraine",
  "description": "Updated description...",
  "employee_count": "100-200",
  "updated_fields": ["name", "description", "employee_count"]
}

Response:

{
  "success": true,
  "entity": {
    "id": "entity_123",
    "updated_at": "2024-01-20T16:45:00Z"
  },
  "message": "Entity updated successfully"
}

DELETE /api/entities/delete/[id]

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

Authentication: Required (Owner or Admin)

Path Parameters:

id (string, required) - Entity identifier

Response:

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

File Management

POST /api/entities/upload

Upload files for entities (logos, images, documents).

Authentication: Required

Content-Type: multipart/form-data

Form Data:

file (File, required) - File to upload
entity_id (string, required) - Entity identifier
type (string, required) - File type (logo, image, document)
description (string, optional) - File description

Response:

{
  "success": true,
  "file": {
    "id": "file_789",
    "name": "company_logo.png",
    "url": "https://storage.com/logos/company_logo.png",
    "type": "logo",
    "size": 156738,
    "uploaded_at": "2024-01-20T17:00:00Z"
  }
}

Premium Content

GET /api/confidential/entities

Access confidential entities for premium members.

Authentication: Required (Confidential role or higher)

Query Parameters: Same as regular entities endpoint

Response: Similar structure to regular entities but includes confidential content

Frontend Integration

Page Routes

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

`/[locale]/entities`

Bundle Size: 1.72 kB + 104 kB

Entity directory with grid/list views
Advanced filtering and search
Category-based navigation
Responsive design

`/[locale]/entities/[id]`

Bundle Size: 39.5 kB + 327 kB

Detailed entity profile
Portfolio showcase
Contact information
Related opportunities

`/[locale]/entities/add`

Bundle Size: 3.53 kB + 294 kB

Entity creation form
Logo and image upload
Rich text description editor
Form validation

`/[locale]/confidential/entities`

Bundle Size: 986 B + 112 kB

Premium entities for verified members
Enhanced entity details
Priority listing placement

React Components

Key components for entity functionality:

// Entity listing component
<EntityList 
  entities={entities}
  filters={filters}
  onFilterChange={handleFilterChange}
  viewMode={viewMode}
/>

// Entity card component
<EntityCard 
  entity={entity}
  showActions={true}
  compact={false}
/>

// Entity creation form
<EntityForm 
  onSubmit={handleSubmit}
  initialData={initialData}
/>

// Entity profile component
<EntityProfile 
  entity={entity}
  showContact={true}
  showOpportunities={true}
/>

Service Architecture

Data Models

Entity Model:

interface Entity {
  id: string
  name: string
  description: string
  short_description?: string
  category: string
  subcategory?: string
  logo?: string
  images: string[]
  website?: string
  location: {
    city?: string
    country?: string
    address?: string
    postal_code?: string
    timezone?: string
  }
  contact: {
    email: string
    phone?: string
    linkedin?: string
    twitter?: string
    facebook?: string
  }
  size: 'startup' | 'small' | 'medium' | 'large'
  employee_count: string
  founded_year?: number
  visibility: 'public' | 'members' | 'confidential'
  is_confidential: boolean
  tags: string[]
  services: string[]
  technologies: string[]
  portfolio: Portfolio[]
  certifications: Certification[]
  achievements: string[]
  opportunities_count: number
  created_at: string
  updated_at: string
  created_by: string
}

Database Operations

The service uses Firebase Firestore with optimized queries:

// Collection reference
const entitiesRef = collection(db, 'entities')

// Query with filters
const query = query(
  entitiesRef,
  where('visibility', 'in', ['public', 'members']),
  where('category', '==', category),
  orderBy('name', 'asc'),
  limit(20)
)

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

Authentication & Authorization

Access control is implemented at multiple levels:

Public Access:

View public entities
Browse categories and locations
Access basic entity information

Member Access:

Create entities (after verification)
Update owned entities
Access member-only entities

Confidential Access:

View confidential entities
Enhanced entity analytics
Priority search results

Admin Access:

Moderate all entities
Manage entity categories
Access comprehensive analytics

Integration Examples

Creating an Entity

import { createEntity } from '@/lib/entities-service'

const handleCreateEntity = async (formData: EntityFormData) => {
  try {
    const entity = await createEntity({
      name: formData.name,
      description: formData.description,
      category: formData.category,
      website: formData.website,
      location: formData.location,
      contact: formData.contact,
      size: formData.size,
      visibility: formData.visibility
    })
    
    router.push(`/${locale}/entities/${entity.id}`)
  } catch (error) {
    toast.error('Failed to create entity')
  }
}

Searching Entities

import { searchEntities } from '@/lib/entities-service'

const handleSearch = async (filters: EntityFilters) => {
  try {
    const result = await searchEntities({
      search: filters.search,
      category: filters.category,
      location: filters.location,
      size: filters.size,
      page: filters.page,
      limit: 20
    })
    
    setEntities(result.entities)
    setPagination(result.pagination)
  } catch (error) {
    toast.error('Search failed')
  }
}

Uploading Entity Media

import { uploadEntityFile } from '@/lib/entities-service'

const handleFileUpload = async (file: File, entityId: string, type: string) => {
  try {
    const upload = await uploadEntityFile(file, entityId, {
      type: type,
      description: `${type} for entity`
    })
    
    if (type === 'logo') {
      setEntity(prev => ({ ...prev, logo: upload.url }))
    }
    
    toast.success('File uploaded successfully')
  } catch (error) {
    toast.error('Failed to upload file')
  }
}

Performance Optimization

Caching Strategy

Client-side caching using React Query for entity listings
Server-side caching for frequently accessed entities
CDN caching for entity logos and images
Database indexing on commonly filtered fields

Bundle Optimization

The entity system is optimized for performance:

Code splitting with dynamic imports for heavy components
Lazy loading for entity images and portfolio items
Pagination to limit data transfer
Image optimization with Next.js Image component

SEO & Internationalization

Localized URLs (/en/entities, /uk/entities)
Meta tags with entity-specific information
Schema.org markup for organization structured data
Sitemap generation for entity pages
Hreflang tags for multilingual SEO

Error Handling

Comprehensive error handling across the service:

// API error responses
{
  "error": true,
  "code": "ENTITY_NOT_FOUND",
  "message": "The requested entity could not be found",
  "details": {
    "entity_id": "entity_123",
    "timestamp": "2024-01-20T18:00:00Z"
  }
}

// Common error codes
- ENTITY_NOT_FOUND
- UNAUTHORIZED_ACCESS
- VALIDATION_ERROR
- DUPLICATE_ENTITY
- QUOTA_EXCEEDED
- UPLOAD_FAILED

Monitoring & Analytics

Metrics Tracked

Entity views and profile engagement
Search performance and popular filters
Registration conversion rates by category
File upload success rates and performance
User interaction patterns with entity profiles

Performance Monitoring

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

The Entity Management Service provides a comprehensive solution for managing organization profiles within the Ring platform, with full internationalization support and optimized performance.

Overview​

API Endpoints​

Core Entity Management​

GET /api/entities​

GET /api/entities/[id]​

POST /api/entities/create​

PUT /api/entities/update/[id]​

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

File Management​

POST /api/entities/upload​

Premium Content​

GET /api/confidential/entities​

Frontend Integration​

Page Routes​

/[locale]/entities​

/[locale]/entities/[id]​

/[locale]/entities/add​

/[locale]/confidential/entities​

React Components​

Service Architecture​

Data Models​

Database Operations​

Authentication & Authorization​

Integration Examples​

Creating an Entity​

Searching Entities​

Uploading Entity Media​

Performance Optimization​

Caching Strategy​

Bundle Optimization​

SEO & Internationalization​

Error Handling​

Monitoring & Analytics​

Metrics Tracked​

Performance Monitoring​

Overview

API Endpoints

Core Entity Management

GET /api/entities

GET /api/entities/[id]

POST /api/entities/create

PUT /api/entities/update/[id]

DELETE /api/entities/delete/[id]

File Management

POST /api/entities/upload

Premium Content

GET /api/confidential/entities

Frontend Integration

Page Routes

`/[locale]/entities`

`/[locale]/entities/[id]`

`/[locale]/entities/add`

`/[locale]/confidential/entities`

React Components

Service Architecture

Data Models

Database Operations

Authentication & Authorization

Integration Examples

Creating an Entity

Searching Entities

Uploading Entity Media

Performance Optimization

Caching Strategy

Bundle Optimization

SEO & Internationalization

Error Handling

Monitoring & Analytics

Metrics Tracked

Performance Monitoring