Quick Start & Development Setup

Relevant source files

The following files were used as context for generating this wiki page:

• deployment/LOCAL_DEVELOPMENT.md
• deployment/QUICK_START.md
• deployment/INDEX.md
• deployment/TESTING.md
• deployment/CREDENTIALS_SETUP.md
• CLAUDE.md

The SecondLayer project is a legal tech platform providing AI-powered document analysis and legal data retrieval. The local development environment is designed to maximize developer productivity by utilizing standard ports, hot-reloading for the frontend, and automated database migrations. It leverages a containerized backend architecture to ensure consistency across different stages of deployment, including staging and production environments.

Sources: deployment/LOCAL_DEVELOPMENT.md:3-12, CLAUDE.md:65-75

Local Development Architecture

The development environment separates frontend and backend processes to optimize for speed. While the frontend runs as a host process with Vite to support hot-reloading, all backend services—including the API, databases, and vector stores—run within Docker containers.

System Component Diagram

The following diagram illustrates the relationship between the local host processes and the containerized backend infrastructure.

Initial Configuration

Setting up the environment requires configuring essential API keys and database credentials. The system uses a manage-gateway.sh script to orchestrate the lifecycle of these services.

Essential Steps

1. Environment Variables: Copy .env.local.example to .env.local and populate required keys such as OPENAI_API_KEY and ZAKONONLINE_API_TOKEN.
2. Credential Validation: Use check-credentials.sh to ensure PostgreSQL superuser and application user passwords are set correctly to avoid authentication failures.
3. Service Initialization: Start the backend using ./manage-gateway.sh start local.

Sources: deployment/LOCAL_DEVELOPMENT.md:38-55, deployment/QUICK_START.md:5-15, deployment/CREDENTIALS_SETUP.md:12-25

Core Configuration Options

Variable	Required	Description	Default/Example
OPENAI_API_KEY	Yes	AI analysis and embeddings	sk-proj-...
ZAKONONLINE_API_TOKEN	Yes	Court database API token	your-token
POSTGRES_USER	Yes	App database user	secondlayer
POSTGRES_PASSWORD	Yes	App user password	local_dev_password
JWT_SECRET	Yes	Secret for JWT authentication	64-char-string

Sources: deployment/LOCAL_DEVELOPMENT.md:175-195, deployment/CREDENTIALS_SETUP.md:105-115

Database Management & Credentials

The system provides an automated initialization and migration flow to prevent common "password authentication failed" errors.

Credential Flow

When the PostgreSQL container starts for the first time, an initialization script automatically creates the application user and database using credentials provided in the .env file.

Service Management Commands

The manage-gateway.sh script is the primary tool for controlling the development environment. It supports various environments including local, dev, stage, and prod.

Common Management Tasks

• Start Backend: ./manage-gateway.sh start local
• Check Status: ./manage-gateway.sh status
• View Logs: ./manage-gateway.sh logs local
• RADA Support: To include parliament data, use docker compose -f docker-compose.local.yml --profile rada up -d.

Sources: deployment/LOCAL_DEVELOPMENT.md:110-125, deployment/INDEX.md:100-115

Testing the Setup

After deployment, the run-local-tests.sh script verifies service integrity. The testing suite includes smoke tests, backend integration tests, and specialized RADA MCP tests.

Test Categories

Suite	Port	Description
Backend Smoke	3000	Verifies basic tool execution and health
Document Service	3002	Tests OCR and PDF processing
RADA MCP	3001	Validates parliament data tools

Sources: deployment/TESTING.md:7-25, deployment/LOCAL_DEVELOPMENT.md:313-325

Automated Testing Workflow

Development Workflow Best Practices

1. Frontend: Run the frontend using npm run dev in the host terminal to utilize Vite's hot-reloading feature.
2. Backend Changes: After editing mcp_backend/src/, rebuild with npm run build inside the directory and restart the local container via manage-gateway.sh.
3. Database: Migrations are run once on startup by the migrate-local service. Manual re-runs can be triggered via docker compose -f docker-compose.local.yml up migrate-local.
4. Cost Optimization: Use gpt-4o-mini for standard tasks and gpt-4o only for deep analysis to minimize API costs during development.

Sources: deployment/LOCAL_DEVELOPMENT.md:140-155, deployment/LOCAL_DEVELOPMENT.md:218-235

The development environment of SecondLayer provides a comprehensive suite of tools to manage a complex legal AI platform. By combining containerized backend services with high-performance frontend tooling, developers can efficiently test, build, and deploy 45+ MCP tools across multiple environments.