Project Overview
Relevant source files
The following files were used as context for generating this wiki page:
SecondLayer is a comprehensive Ukrainian legal tech platform designed to provide AI-powered legal document analysis, semantic search over court decisions, and legislation retrieval. It leverages a modular architecture based on the Model Context Protocol (MCP) to integrate various legal data sources, including the ZakonOnline court database, Verkhovna Rada open data, and state business registries.
The platform is structured as a monorepo consisting of multiple specialized MCP servers, a modern React-based frontend, and shared packages. It facilitates complex legal workflows such as time tracking, billing, and document management while providing a unified gateway for AI assistants to access up to 45 different legal tools.
Sources: CLAUDE.md:61-75, lexwebapp/COMPLETE_REFACTORING_SUMMARY.md:4-10
System Architecture
SecondLayer utilizes a distributed architecture with multiple backend services orchestrated through an MCP-based gateway. The system supports a "Triple Transport System" including MCP stdio for local integration, a RESTful HTTP API for web applications, and Server-Sent Events (SSE) for remote streaming capabilities.
Core Components
The workspace is divided into several high-level modules:
| Component | Description |
|---|---|
mcp_backend | Primary server handling court cases, legal documents (ZakonOnline), and core legal logic. |
mcp_rada | Parliament data server for tracking deputies, bills, legislation, and voting records. |
mcp_openreyestr | State Register server for business entities, beneficiaries, and debtors. |
lexwebapp | Frontend application built with React 19, Vite, and TailwindCSS. |
packages/shared | Common TypeScript types, utilities, and LLM managers used across services. |
deployment | Infrastructure configuration including Docker Compose, Nginx, and management scripts. |
Sources: CLAUDE.md:77-101, deployment/LOCAL_DEVELOPMENT.md:85-110
High-Level Architecture Diagram
The following diagram illustrates the relationship between the frontend, backend services, and external data providers:
The diagram shows the user interacting with the React frontend, which communicates via a unified gateway to various MCP backend servers. These servers interact with local databases (PostgreSQL, Qdrant, Redis) and external legal data providers.
Sources: CLAUDE.md:80-110, deployment/LOCAL_DEVELOPMENT.md:85-105
Backend Infrastructure and Services
The backend is built on Node.js 20 and TypeScript, utilizing a factory pattern for service initialization. This allows for clean composition of database connections, caching layers, and LLM managers.
Key Backend Services
The mcp_backend contains several critical services for legal analysis:
- QueryPlanner: Classifies user intent to select the optimal search strategy.
- SemanticSectionizer: Breaks legal documents into logical articles and parts for granular retrieval.
- CitationValidator: Validates legal citations against source documents to prevent AI hallucinations.
- CostTracker: Tracks API usage costs for OpenAI, Anthropic, and other providers per request.
- VaultService: Manages secure document storage and retrieval.
Sources: CLAUDE.md:118-140, mcp_rada/IMPLEMENTATION_STATUS.md:145-165
Implementation Phases
The project is being developed in distinct phases to implement "P0 Critical Features":
| Phase | Feature | Status | Key Tables |
|---|---|---|---|
| Phase 1 | Time Tracking & Billing | Completed | time_entries, matter_invoices, active_timers |
| Phase 2 | Tasks & Documents | Planned | tasks, matter_deadlines, document_shares |
| Phase 3 | Communication Hub | Planned | matter_messages, notifications |
| Phase 4 | Client Portal | Planned | client_users, signature_requests |
Sources: IMPLEMENTATION_PHASES.md:5-25
Frontend Architecture
The lexwebapp underwent a major refactoring to move from a monolithic "God Component" (ChatLayout) to a modern, scalable React architecture.
Refactored Structure
The new architecture prioritizes separation of concerns through:
- React Router: Implements URL-based navigation, enabling deep linking and browser history support.
- Service Layer: Centralizes API logic into dedicated services (Legal, Auth, Billing, Client) with over 23 methods.
- State Management: Utilizes Zustand for persistent UI/Chat state and TanStack Query (React Query) for server-side state and caching.
- UI Component Library: A consistent design system with WCAG 2.1 AA compliant components (Buttons, Modals, Cards).
Sources: lexwebapp/COMPLETE_REFACTORING_SUMMARY.md:12-65, lexwebapp/MIGRATION_GUIDE.md:8-35
Frontend Data Flow Diagram
This sequence diagram illustrates the real-time SSE streaming flow from a user query in the UI to the backend and back through the specialized useMCPTool hook.
Sources: lexwebapp/BUILD_SUMMARY.md:15-40, lexwebapp/TEST_INSTRUCTIONS.md:30-50
Deployment and Environments
The project supports three primary environments with standardized port allocations for local development and staging.
Environment Matrix
| Environment | Host | URL | Purpose |
|---|---|---|---|
| Local | localhost | http://localhost:5173 | Developer productivity with hot-reload and direct service access. |
| Staging | mail.lexapp.co.ua | https://stage.legal.org.ua | Unified gateway environment aggregating all 45 tools for testing. |
| Production | gate-server | https://legal.org.ua | High-availability production environment. |
Sources: deployment/LOCAL_DEVELOPMENT.md:112-125, deployment/README.md:5-15, CLAUDE.md:166-175
Deployment Infrastructure
Deployment is managed via Docker Compose, utilizing multiple containers for different parts of the stack:
- Database: PostgreSQL 15 (Metadata), Qdrant (Vectors), Redis 7 (Caching).
- Proxy: Nginx configured as a reverse proxy with modular includes for OAuth, MCP, and API endpoints.
- Monitoring: Prometheus and Grafana integration for system health tracking.
Sources: mcp_backend/DEPLOYMENT.md:195-210, deployment/nginx/README.md:15-45
Conclusion
SecondLayer represents a highly modular approach to legal technology, combining specialized data adapters with advanced AI orchestration. By utilizing the Model Context Protocol and a robust streaming frontend, it provides legal professionals with high-performance tools for document analysis and legal research while maintaining strict data integrity and cost transparency.
Sources: CLAUDE.md:14-25, lexwebapp/COMPLETE_REFACTORING_SUMMARY.md:145-160