Skip to main content

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.