System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The SecondLayer platform is a Ukrainian legal tech monorepo designed for AI-powered document analysis, semantic search, and legal practice management. It utilizes a Triple Transport System for its Model Context Protocol (MCP) servers, enabling communication via MCP stdio, HTTP REST API, and Server-Sent Events (SSE). The architecture is built on a modular, service-oriented foundation that integrates specialized backend servers with a modern React-based frontend.
Sources: CLAUDE.md:1-20, lexwebapp/BUILD_SUMMARY.md:10-25
Core Backend Infrastructure
The backend is composed of several specialized MCP servers and support services orchestrated through a unified gateway.
Triple Transport System
Each MCP server in the ecosystem supports three primary communication protocols:
- MCP stdio: Facilitates standard integration with local AI clients like Claude Desktop.
- HTTP API: Provides standard REST endpoints (
/api/tools/:toolName) for web application integration. - SSE (Server-Sent Events): Enables real-time, remote MCP communication over HTTPS for distributed clients.
Sources: CLAUDE.md:65-72, lexwebapp/BUILD_SUMMARY.md:60-65
Service Decomposition
The platform splits logic across multiple dedicated servers:
- mcp_backend: The primary server handling court cases, legal documents (via ZakonOnline), and core AI services like semantic search and citation validation.
- mcp_rada: A dedicated server for Ukrainian parliament data, including deputies, bills, and legislation texts.
- mcp_openreyestr: Handles business registry lookups, including entities, beneficiaries, and debtors.
- Document Service: A specialized service focused on OCR and document processing (e.g., Google Cloud Vision integration).
Sources: CLAUDE.md:38-55, deployment/LOCAL_DEVELOPMENT.md:70-85
Unified Gateway Flow
In stage and production environments, a unified gateway aggregates tools from all services.
The diagram shows how the Unified Gateway routes requests to specific MCP servers and their respective data stores.
Sources: CLAUDE.md:78-85, deployment/LOCAL_DEVELOPMENT.md:100-120
Frontend Architecture
The frontend (lexwebapp) follows a clean, decoupled architecture implemented during a comprehensive refactoring phase. It emphasizes separation of concerns through a service layer and modern state management.
Architectural Layers
- Routing & Guards: Utilizes React Router for URL-based navigation and an
AuthGuardfor session protection. - Service Layer: Centralized API logic (e.g.,
LegalService,AuthService,BillingService) that encapsulates HTTP calls. - State Management: Uses Zustand for lightweight persistent stores (chat, UI settings) and TanStack Query for server-state caching and synchronization.
- UI Component Library: A standardized design system with reusable, accessible components.
Sources: lexwebapp/COMPLETE_REFACTORING_SUMMARY.md:35-100, lexwebapp/BUILD_SUMMARY.md:40-55
Frontend Data Flow
The frontend architecture ensures that UI components do not interact directly with APIs.
This sequence diagram illustrates the flow of a streaming MCP tool call from the UI to the backend via SSE.
Sources: lexwebapp/BUILD_SUMMARY.md:30-45, lexwebapp/COMPLETE_REFACTORING_SUMMARY.md:150-170
Data Management & Intelligence
The platform uses a sophisticated data stack to handle structured, relational, and vector data.
Storage Layer Comparison
| Service | Primary Database | Vector Store | Cache |
|---|---|---|---|
| mcp_backend | PostgreSQL 15 | Qdrant | Redis 7 |
| mcp_rada | PostgreSQL 15 (Port 5433) | Qdrant | Redis (Port 6380) |
| mcp_openreyestr | PostgreSQL 15 (Port 5435) | N/A | Redis (Port 6382) |
Sources: CLAUDE.md:95-100, mcp_rada/IMPLEMENTATION_STATUS.md:15-30
Dynamic Template System
The platform includes a self-learning legal knowledge system that follows a 5-stage pipeline for processing legal queries:
- Classification: Uses LLMs to determine intent and extract entities (dates, amounts).
- Matching: Performs semantic similarity search in Qdrant to find existing templates.
- Generation: Auto-generates new Mustache-based templates if match scores fall below a 0.65 threshold.
- Storage: Manages versioning (MAJOR/MINOR/PATCH) and admin review.
- Recommendations: Provides suggestions based on frequency, trending, and user context.
Sources: mcp_backend/src/services/template-system/README.md:5-40
Intelligence Services
- QueryPlanner: Classifies user intent and selects search strategies.
- SemanticSectionizer: Breaks legal documents into logical sections (articles/parts) for granular retrieval.
- LegalPatternStore: Manages legal reasoning patterns stored in the Qdrant vector database.
- ModelSelector: Implements budget-aware logic to route tasks:
- Quick:
gpt-4o-mini - Standard:
gpt-4o-mini - Deep:
gpt-4o
- Quick:
Sources: CLAUDE.md:120-140, mcp_rada/IMPLEMENTATION_STATUS.md:40-45
Deployment & Environments
The system is containerized using Docker and managed via a unified script (manage-gateway.sh).
Network & Port Configuration
| Environment | Backend Port | Frontend Port | Base URL |
|---|---|---|---|
| Local | 3000 | 5173 | localhost |
| Staging | 3004 | 8092 | stage.legal.org.ua |
Sources: deployment/LOCAL_DEVELOPMENT.md:88-105, CLAUDE.md:250-260
Architecture Summary
The SecondLayer architecture is a robust, monorepo-based system designed for high scalability and technical accuracy in the legal domain. By leveraging specialized MCP servers, a triple-transport communication layer, and a modern frontend stack, it provides a performant environment for complex legal document analysis and practice management.
Sources: CLAUDE.md:30-45, lexwebapp/COMPLETE_REFACTORING_SUMMARY.md:10-25