Eidos Documentation

Comprehensive technical documentation for the Eidos Ontology Builder application.

Overview

What is Eidos?

Eidos is a modern, production-ready web application for creating, managing, and visualizing ontologies. Built with Blazor Server and .NET 9, it provides an intuitive interface for knowledge organization and semantic modeling.

Key Capabilities

Visual Ontology Editor - Interactive graph-based concept and relationship management
Real-time Collaboration - Multiple users can work on the same ontology simultaneously
Import/Export - Full TTL (Turtle) format support for interoperability
Permission System - Group-based access control with fine-grained permissions
Version Control - Complete activity tracking with before/after snapshots
Multiple Views - Graph, List, Hierarchy, TTL, and Notes views

Technology Stack

Frontend

Blazor Server (.NET 9)
Bootstrap 5
Cytoscape.js (Graph Visualization)
SignalR (Real-time)

Backend

ASP.NET Core
Entity Framework Core
Azure SQL Database
Azure App Service

Architecture

Application Architecture

Eidos follows a clean, layered architecture with clear separation of concerns:

┌─────────────────────────────────────┐
│      Blazor UI Components Layer      │
│   (Pages, Components, Dialogs)       │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│         Services Layer               │
│  (Business Logic, Orchestration)     │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│       Repository Layer               │
│   (Data Access Abstraction)          │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│      Entity Framework Core           │
│         (ORM Layer)                  │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│       Azure SQL Database             │
│        (Data Storage)                │
└─────────────────────────────────────┘

SOLID Principles Applied

Single Responsibility Principle (SRP): Each service has a focused purpose (e.g., OntologyService, ConceptService, RelationshipService)
Open/Closed Principle (OCP): Services and repositories are extensible through interfaces without modifying existing code
Liskov Substitution Principle (LSP): Repository implementations can be substituted without breaking functionality
Interface Segregation Principle (ISP): Interfaces are focused and minimal (e.g., IRepository<T>, IOntologyService)
Dependency Inversion Principle (DIP): Components depend on abstractions (interfaces), not concrete implementations

Project Structure

Eidos/
├── Components/
│   ├── Pages/              # Routable pages
│   ├── Ontology/          # Ontology-specific components
│   ├── Shared/            # Shared components (NavBar, etc.)
│   └── Layout/            # Layout components
├── Services/
│   ├── Interfaces/        # Service contracts
│   └── *.cs              # Service implementations
├── Data/
│   ├── Repositories/      # Data access layer
│   ├── OntologyDbContext.cs
│   └── ApplicationDbContext.cs
├── Models/               # Domain entities
├── Hubs/                # SignalR hubs
├── Exceptions/          # Custom exceptions
└── wwwroot/
    ├── css/
    ├── js/
    └── lib/

Core Concepts

Data Models

Entity Relationship Diagram

Simplified view of core entities and their relationships:

User (ApplicationUser)
  │
  ├── owns ──── Ontology
  │                 │
  │                 ├── contains ──── Concept
  │                 │                      │
  │                 ├── contains ──── Relationship
  │                 │                      │
  │                 ├── tracked by ── OntologyActivity
  │                 │
  │                 └── has permissions ── OntologyGroupPermission
  │                                               │
  │                                               │
  ├── member of ── UserGroupMember ── in ── UserGroup
  │
  └── preferences ── UserPreferences

Database Tables

Table	Purpose	Key Relationships
`Ontologies`	Top-level knowledge containers	User (owner), OntologyActivity, Concepts, Relationships
`Concepts`	Entities/classes within ontologies	Ontology, Relationships (as source/target)
`Relationships`	Connections between concepts	Ontology, SourceConcept, TargetConcept
`AspNetUsers`	User accounts and authentication	Ontologies, UserGroupMembers, UserPreferences
`UserGroups`	Groups for permission management	UserGroupMembers, OntologyGroupPermissions
`OntologyGroupPermissions`	Group access grants for ontologies	Ontology, UserGroup
`OntologyActivity`	Version history and change tracking	Ontology, User
`UserPreferences`	User settings and preferences	User

Services Layer

Service Architecture

Services encapsulate business logic and orchestrate operations across repositories. All services implement interfaces for testability and dependency inversion.

OntologyService

Manages ontology lifecycle and operations.

Key Methods:

CreateOntologyAsync()
CloneOntologyAsync()
GetOntologyDescendantsAsync()
UpdateVisibilityAsync()
GetAccessibleOntologiesAsync()

Optimization: Batch operations use AddRange() for 80% faster cloning

ConceptService

Manages concepts within ontologies.

Key Methods:

CreateAsync()
GetByOntologyIdAsync()
GetParentConceptsAsync()
GetChildConceptsAsync()
UpdatePositionAsync()

Optimization: Batch queries with WHERE IN reduce N+1 issues by 60-80%

RelationshipService

Manages relationships between concepts.

Key Methods:

CreateAsync()
GetByOntologyIdAsync()
GetBySourceConceptAsync()
GetByTargetConceptAsync()
ValidateRelationshipAsync()

OntologyPermissionService

Manages group-based access control.

Key Methods:

CanViewAsync()
CanEditAsync()
CanManageAsync()
GrantGroupAccessAsync()
RevokeGroupAccessAsync()
GetAccessibleOntologiesAsync()

UserManagementService

Manages users, roles, and groups.

Key Methods:

GetAllUsersAsync()
AssignRoleAsync()
CreateGroupAsync()
AddUserToGroupAsync()
GetGroupMembersAsync()

TtlExportService

Exports ontologies to Turtle (TTL) format.

Key Methods:

ExportOntologyToTtlAsync()
GenerateConceptTtl()
GenerateRelationshipTtl()

Standards: Supports RDF, RDFS, OWL, BFO, PROV-O

Design Patterns

Command Pattern

Encapsulates actions as objects for undo/redo functionality.

Implementation:

ICommand interface with Execute/Undo
CommandManager with undo/redo stacks
6 command types: Create/Update/Delete Concept/Relationship
Per-ontology command history (max 50)

Location: Services/Commands/

Repository Pattern

Abstracts data access logic from business logic.

Implementation:

IRepository<T> base interface
BaseRepository<T> with common CRUD
Specialized: OntologyRepository, ConceptRepository, etc.
AsNoTracking() for read operations (10-20% faster)

Location: Data/Repositories/

Factory Pattern

Creates command objects based on operation type.

Implementation:

CommandFactory creates appropriate command instances
Used by UI to create undoable operations
Dependency injection for service resolution

Example: CreateConceptCommand, DeleteRelationshipCommand

Facade Pattern

Simplifies complex subsystem interactions.

Implementation:

Services provide unified interface to repositories
OntologyService coordinates Concept + Relationship operations
UI components interact with services, not repositories

Benefit: Reduced coupling, easier testing

Strategy Pattern

Defines interchangeable algorithms (export strategies).

Implementation:

Export strategies for TTL, JSON, CSV formats
Template strategies for BFO, PROV-O, custom
Validation strategies by entity type

Benefit: Easy to add new export formats

Observer Pattern

Event-driven updates for real-time collaboration.

Implementation:

SignalR broadcasts changes to connected clients
Components subscribe to ontology-specific groups
Automatic UI refresh on remote changes

Hub: OntologyHub

Security

Security Architecture

Multi-layered security approach with defense in depth.

Authentication:

ASP.NET Core Identity - User account management
OAuth 2.0 - Third-party authentication (GitHub, Google, Microsoft)
Strong Passwords - Min 8 chars, mixed case, numbers, special chars
Account Lockout - 5 failed attempts = 15 minute lockout
Secure Sessions - 24 hour expiration with sliding renewal

Authorization:

Role-Based Access Control (RBAC) - Admin, PowerUser, User, Guest
Group-Based Permissions - View, Edit, Admin levels per ontology
Ownership Model - Creator has full control
Visibility Levels - Private, Group, Public
Permission Inheritance - Most restrictive wins

Infrastructure Security:

HTTPS Only - All traffic encrypted with TLS 1.2+
HSTS - HTTP Strict Transport Security enabled
CSP - Content Security Policy headers
XSS Protection - X-XSS-Protection header
Frame Options - X-Frame-Options: DENY
Content Type Sniffing - X-Content-Type-Options: nosniff

Rate Limiting:

Authentication endpoints: 5 attempts / 15 minutes
API endpoints: 100 requests / minute
SignalR connections: 10 connections / user

Secrets Management:

Azure Key Vault - Centralized secret storage
Managed Identity - No credentials in code
Environment Variables - Local development
Never commit secrets to source control

Security Best Practices

Always validate user permissions before operations
Use parameterized queries (EF Core) to prevent SQL injection
Sanitize user input in UI components
Log security events (failed logins, permission violations)
Regular security audits via Application Insights
Keep dependencies updated for security patches

Real-Time Collaboration

SignalR Architecture

Enables multiple users to work on the same ontology simultaneously with real-time updates.

OntologyHub:

public class OntologyHub : Hub
{
    // Join an ontology group
    Task JoinOntologyGroup(int ontologyId);

    // Broadcast concept changes
    Task BroadcastConceptAdded(Concept concept);
    Task BroadcastConceptUpdated(Concept concept);
    Task BroadcastConceptDeleted(int conceptId);

    // Broadcast relationship changes
    Task BroadcastRelationshipAdded(Relationship rel);
    Task BroadcastRelationshipUpdated(Relationship rel);
    Task BroadcastRelationshipDeleted(int relId);
}

Client-Side Integration:

Components subscribe to hub on initialization
Automatically join ontology-specific groups
Listen for broadcast events and update UI
Prevent echo (don't react to own changes)
Graceful reconnection on disconnect

Permission Verification:

Hub validates user permissions before broadcasting
Only authorized users receive updates
Guest users tracked via session tokens

Sharing & Guest Access

Share Link Generation:

Cryptographically secure token generation
Permission levels: View, Comment, Edit, Admin
Optional guest access toggle
Time-based expiration support
Access tracking and analytics

Guest Sessions:

Session tokens for anonymous users
IP address and user agent tracking
Activity monitoring
Automatic cleanup of inactive sessions

UI Components

Component Structure

Blazor components organized by feature area for maintainability.

Components/
├── Pages/                    # Routable pages (@page directive)
│   ├── Home.razor           # Dashboard
│   ├── OntologyView.razor   # Main editor
│   ├── Learn.razor          # Tutorial
│   ├── Features.razor       # Feature showcase
│   └── Documentation.razor  # This page
├── Ontology/                # Ontology-specific components
│   ├── ConceptDialog.razor
│   ├── RelationshipDialog.razor
│   ├── OntologySettingsDialog.razor
│   ├── HistoryPanel.razor
│   └── CollaboratorsPanel.razor
├── Shared/                  # Shared components
│   ├── NavMenu.razor
│   ├── ToastContainer.razor
│   └── ReleaseNotes.razor
└── Layout/                  # Layout components
    └── MainLayout.razor

OntologyView.razor

Main ontology editor with multiple view modes.

Features:

5 view modes (Graph, List, Hierarchy, TTL, Notes)
Real-time collaboration via SignalR
Undo/redo with command pattern
Permission-based editing
Keyboard shortcuts
Responsive design

ConceptDialog.razor

Create/edit concepts with full metadata.

Fields:

Name, Definition, Description
Category (Entity, Process, Quality, Role, Event)
URI, Color
Custom properties (key-value pairs)
Template selection

HistoryPanel.razor

Version history with before/after comparison.

Features:

Timeline view of all changes
Filter by entity type and activity
Statistics dashboard
Diff viewer
Contributor breakdown

OntologySettingsDialog.razor

Manage ontology metadata and permissions.

Tabs:

General: Name, description, author, version
Permissions: Visibility, group access, permission levels

Graph Visualization

Interactive graph powered by Cytoscape.js with D3.js force-directed layout.

Features:

Pan & Zoom: Navigate large ontologies
Drag & Drop: Reposition concepts
Click Interactions: Select concepts/relationships
Context Menus: Quick actions on right-click
Auto-Layout: Automatic graph organization
Export: Save as PNG/SVG

JavaScript Integration: wwwroot/js/graphVisualization.js

Testing

Test Strategy

Comprehensive test coverage with 157+ tests ensuring reliability.

Test Pyramid:

         /\
        /  \    Component Tests (36 tests)
       /────\   - UI behavior, user interactions
      /      \
     /────────\ Integration Tests (65+ tests)
    /          \ - Services with database
   /────────────\ Unit Tests (56+ tests)
  /              \ - Business logic, models
 /────────────────\

Unit Tests (56+)

Covered Areas:

Service unit tests (58 tests)
LoginModel tests (12 tests)
Command pattern tests
Validation logic

Tools: xUnit, Moq

Integration Tests (65+)

Covered Areas:

Repository tests (19 tests)
Service integration tests (45+ tests)
OntologyPermissionService (20+ tests)
Database operations

Tools: EF Core In-Memory Database

Component Tests (36)

Covered Areas:

Blazor component rendering
User interactions
Event handling
Parameter binding

Tools: bUnit

Workflow Tests (7)

Covered Areas:

End-to-end scenarios
Multi-service workflows
Permission flows
User journeys

Examples: Clone ontology, Permission grant

Running Tests

# Run all tests
dotnet test

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

# Run specific test category
dotnet test --filter "FullyQualifiedName~Integration"
dotnet test --filter "FullyQualifiedName~Unit"
dotnet test --filter "FullyQualifiedName~Component"

# Run specific test class
dotnet test --filter "FullyQualifiedName~OntologyPermissionServiceTests"

Deployment

Azure Infrastructure

Resources:

Azure App Service: Hosts the Blazor Server application
Azure SQL Database: GP_S_Gen5_1 (serverless, 0.5-1 vCore)
Azure Key Vault: Stores secrets and connection strings
Application Insights: Monitoring and telemetry
Managed Identity: Secure access to Azure resources

Configuration:

HTTPS-only with TLS 1.2
Custom domain: https://eidosonto.com
Auto-scaling based on demand
Database auto-pause after 60 minutes of inactivity
Application Insights daily cap: 300 MB

CI/CD Pipeline

GitHub Actions workflow for automated deployment.

Workflow Steps:

Trigger: Push to main branch or manual dispatch
Checkout code
Setup .NET 9
Restore dependencies
Build project (dotnet build --no-restore)
Run tests (dotnet test --no-build)
Publish release (dotnet publish -c Release)
Deploy to Azure App Service
Run health checks
Post-deployment validation

File: .github/workflows/azure-deploy.yml

Database Migrations

Entity Framework Core Migrations:

# Create migration
dotnet ef migrations add MigrationName

# Apply migrations
dotnet ef database update

# Generate SQL script
dotnet ef migrations script

# List migrations
dotnet ef migrations list

Production Deployment:

Migrations run automatically during app startup
Connection string loaded from Azure Key Vault
Azure SQL firewall allows App Service access only

Monitoring & Observability

Application Insights Tracking:

Request/response metrics
Exception logging with stack traces
Custom events for business metrics
User session analytics
Performance counters
Dependency tracking (SQL, HTTP)

Health Checks:

Database connectivity
SignalR hub status
Endpoint: /health

Questions or Need Help?

This documentation covers the core architecture and implementation details of Eidos. For additional information or support, please refer to the codebase or contact the development team.

Back to Dashboard View Features Learn Tutorial

Contents

Eidos Documentation

Overview

What is Eidos?

Key Capabilities

Technology Stack

Frontend

Backend

Architecture

Application Architecture

SOLID Principles Applied

Project Structure

Core Concepts

1. Ontology

2. Concept

3. Relationship

4. User & Authentication

5. Groups & Permissions

6. Activity Tracking & Version Control

Data Models

Entity Relationship Diagram

Database Tables

Services Layer

Service Architecture

Key Methods:

Key Methods:

Key Methods:

Key Methods:

Key Methods:

Key Methods:

Design Patterns

Implementation:

Implementation:

Implementation:

Implementation:

Implementation:

Implementation:

Security

Authentication:

Authorization:

Infrastructure Security:

Rate Limiting:

Secrets Management:

Real-Time Collaboration

OntologyHub:

Client-Side Integration:

Permission Verification:

Share Link Generation:

Guest Sessions:

UI Components

Component Structure

Features:

Fields:

Features:

Tabs:

Features:

Testing

Test Pyramid:

Covered Areas:

Covered Areas:

Covered Areas:

Covered Areas:

Deployment

Resources:

Configuration:

Workflow Steps:

Entity Framework Core Migrations:

Production Deployment:

Application Insights Tracking:

Health Checks:

Questions or Need Help?