Concept Browser

A web application for medical researchers to evaluate the feasibility of clinical studies by analyzing OMOP CDM (Common Data Model) concepts and data availability across healthcare databases.

Overview

Concept Browser streamlines the study feasibility assessment process by:

• Searching and managing medical concepts from OMOP CDM
• Creating and organizing concept sets for study definitions
• Analyzing data availability across multiple data sources
• Building complex concept relationships using AND/OR/EXCLUDE operators
• Generating comprehensive feasibility reports with record counts and statistical analysis

Key Features

Concept Search & Management

• Full-text search across OMOP CDM vocabulary
• Concept hierarchy navigation with ancestor/descendant relationships
• Support for multiple domains (medications, conditions, procedures, etc.)
• Quick concept filtering and organization

Study Management

• Create and manage multiple clinical studies
• Define inclusion/exclusion criteria using concept sets
• Track study metadata and specifications
• Version history and study tracking

Feasibility Analysis

• Real-time record count estimates across data sources
• Statistical summaries (min/max/mean records)
• Data source-specific analysis and comparison
• Achilles analysis integration for aggregated statistics
• Concept distribution charts and visualizations

Custom Relationships

• Build complex concept combinations with logical operators:
  • AND (Intersection): Find records matching all concepts
  • OR (Union): Find records matching any concept
  • EXCLUDE: Subtract excluded concepts from base set
• Validate relationship logic before feasibility calculation
• Save drafts and activate relationships

📱 Responsive UI

• Clean, intuitive interface for researchers
• Dark mode support
• Mobile-friendly design
• Real-time data updates

Architecture

Technology Stack

Frontend:

• Next.js 16+ (React 19)
• TypeScript
• TailwindCSS + shadcn/ui
• React Query for data fetching
• Recharts for visualizations
• React Hook Form for forms

Backend:

• FastAPI (Python 3.12+)
• SQLModel (SQLAlchemy ORM)
• PostgreSQL 17
• Uvicorn ASGI server

Infrastructure:

• Docker & Docker Compose for containerization
• PostgreSQL for data persistence
• Automated data loading pipeline

Quick Start

Prerequisites

• Docker and Docker Compose
• Git

Installation & Setup

1. Clone the repository

   git clone https://github.com/yourusername/concept-browser.git
   cd concept-browser

2. Configure environment variables

   cp .env.example .env
   # Edit .env with your database credentials and settings

3. Start with Docker Compose

   docker-compose -f docker-compose.dev.yaml up -d

4. Access the application

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/docs

Manual Setup (Development)

Backend:

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .
uvicorn app.main:app --reload

Frontend:

cd frontend
npm install
npm run dev

Project Structure

concept-browser/
├── backend/                 # FastAPI backend application
│   ├── app/
│   │   ├── routers/        # API endpoints (concepts, studies, feasibility)
│   │   ├── services/       # Business logic layer
│   │   ├── repositories/   # Database queries
│   │   ├── models/         # SQLModel database models
│   │   ├── schemas/        # Pydantic request/response schemas
│   │   └── core/           # Configuration, database, dependencies
│   └── docker/
├── frontend/               # Next.js frontend application
│   ├── src/
│   │   ├── app/           # Next.js app directory (pages)
│   │   ├── components/    # Reusable React components
│   │   ├── hooks/         # Custom React hooks
│   │   ├── types/         # TypeScript type definitions
│   │   └── lib/           # Utilities and helpers
│   └── docker/
├── data_loader/           # Data loading pipeline
├── data/                  # OMOP CDM concept data files
└── docker-compose.dev.yaml

API Endpoints

Concepts

• GET /concepts/search - Search concepts with filters
• GET /concepts/{concept_id} - Get concept details
• GET /concepts/{concept_id}/ancestors - Get ancestor concepts
• GET /concepts/{concept_id}/descendants - Get descendant concepts

Studies

• GET /studies - List all studies
• POST /studies - Create new study
• GET /studies/{study_id} - Get study details
• PUT /studies/{study_id} - Update study
• DELETE /studies/{study_id} - Delete study

Feasibility

• POST /studies/{study_id}/feasibility - Run feasibility analysis
• GET /studies/{study_id}/feasibility - Get feasibility results
• GET /studies/{study_id}/feasibility/data-sources - Data source analysis

Relationships

• POST /studies/{study_id}/relationships - Create relationship
• GET /studies/{study_id}/relationships - List relationships
• PUT /studies/{study_id}/relationships/{relationship_id} - Update relationship
• DELETE /studies/{study_id}/relationships/{relationship_id} - Delete relationship

For complete API documentation, see Backend README or visit /docs endpoint.

Configuration

Key environment variables:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/concept_browser

# Backend
BACKEND_PORT=8000

# Frontend
NEXT_PUBLIC_API_URL=http://localhost:8000

See .env.example for all available configuration options.

Data & References

• OMOP Common Data Model Documentation
• Concept Model Reference
• OHDSI Community

Development

Running Tests

# Backend
cd backend
pytest

# Frontend
cd frontend
npm run test

Code Quality

# Backend linting
cd backend
pylint app/

# Frontend linting
cd frontend
npm run lint
npm run format

Troubleshooting

Database Connection Issues

• Ensure PostgreSQL is running and accessible
• Check DATABASE_URL in .env is correct
• Verify database user has necessary permissions

Port Already in Use

• Change ports in docker-compose.dev.yaml or environment
• Kill existing processes: lsof -i :PORT | grep LISTEN | awk '{print $2}' | xargs kill -9

Frontend Can't Connect to Backend

• Verify backend is running (http://localhost:8000/health)
• Check NEXT_PUBLIC_API_URL in frontend environment
• Check CORS settings in backend/app/main.py

Contributing

1. Create a feature branch (git checkout -b feature/AmazingFeature)
2. Commit changes (git commit -m 'Add AmazingFeature')
3. Push to branch (git push origin feature/AmazingFeature)
4. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support & Questions

For questions or issues:

• Create an issue on GitHub
• Check existing issues and documentation
• Review the API documentation at /docs endpoint