add pg vector and embed
This commit is contained in:
473
README.md
473
README.md
@@ -1,194 +1,397 @@
|
||||
<p align="center">
|
||||
<a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="120" alt="Nest Logo" /></a>
|
||||
</p>
|
||||
# 🏥 Claim Guard Backend
|
||||
|
||||
[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456
|
||||
[circleci-url]: https://circleci.com/gh/nestjs/nest
|
||||
> **NestJS application for managing ICD-9 and ICD-10 medical codes with Excel import functionality**
|
||||
|
||||
<p align="center">A progressive <a href="http://nodejs.org" target="_blank">Node.js</a> framework for building efficient and scalable server-side applications.</p>
|
||||
<p align="center">
|
||||
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
|
||||
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
|
||||
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/dm/@nestjs/common.svg" alt="NPM Downloads" /></a>
|
||||
<a href="https://circleci.com/gh/nestjs/nest" target="_blank"><img src="https://img.shields.io/circleci/build/github/nestjs/nest/master" alt="CircleCI" /></a>
|
||||
<a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
|
||||
<a href="https://opencollective.com/nest#backer" target="_blank"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
|
||||
<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
|
||||
<a href="https://paypal.me/kamilmysliwiec" target="_blank"><img src="https://img.shields.io/badge/Donate-PayPal-ff3f59.svg" alt="Donate us"/></a>
|
||||
<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://img.shields.io/badge/Support%20us-Open%20Collective-41B883.svg" alt="Support us"></a>
|
||||
<a href="https://twitter.com/nestframework" target="_blank"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow" alt="Follow us on Twitter"></a>
|
||||
</p>
|
||||
<!--[](https://opencollective.com/nest#backer)
|
||||
[](https://opencollective.com/nest#sponsor)-->
|
||||
[](https://nestjs.com/)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](https://www.postgresql.org/)
|
||||
[](https://www.docker.com/)
|
||||
[](https://www.prisma.io/)
|
||||
|
||||
## Description
|
||||
## ✨ Features
|
||||
|
||||
Claim Guard Backend - A NestJS application for managing ICD-9 and ICD-10 medical codes with Excel import functionality.
|
||||
- 🏥 **ICD Code Management** - Import and manage ICD-9 and ICD-10 medical codes
|
||||
- 📊 **Excel Import** - Read data from Excel files and store in PostgreSQL
|
||||
- 🔍 **Search & Filter** - Search codes by category, code, or display text
|
||||
- 🌐 **REST API** - Full REST API with Swagger documentation
|
||||
- 📄 **Pagination** - Built-in pagination for large datasets
|
||||
- 🐳 **Docker Ready** - PostgreSQL with pgvector extension
|
||||
- 🔄 **Database Migrations** - Prisma migration system
|
||||
- ✅ **Input Validation** - Type-safe DTOs with validation
|
||||
- 📚 **API Documentation** - Interactive Swagger UI
|
||||
|
||||
## Features
|
||||
## 🚀 Quick Start
|
||||
|
||||
- **ICD Code Management**: Import and manage ICD-9 and ICD-10 medical codes
|
||||
- **Excel Import**: Read data from Excel files and store in PostgreSQL database
|
||||
- **Search & Filter**: Search codes by category, code, or display text
|
||||
- **REST API**: Full REST API endpoints for accessing ICD data
|
||||
- **Pagination**: Built-in pagination support for large datasets
|
||||
### Prerequisites
|
||||
|
||||
## ICD Service Endpoints
|
||||
- Node.js 18+
|
||||
- Docker & Docker Compose
|
||||
- Git
|
||||
|
||||
### Import Data
|
||||
|
||||
```bash
|
||||
POST /icd/import
|
||||
```
|
||||
|
||||
Imports ICD-9 and ICD-10 data from Excel files in the `test/` directory.
|
||||
|
||||
### Search Codes
|
||||
|
||||
```bash
|
||||
GET /icd/search?category=ICD10&search=diabetes&page=1&limit=10
|
||||
```
|
||||
|
||||
Search ICD codes with optional filters:
|
||||
|
||||
- `category`: Filter by ICD9 or ICD10
|
||||
- `search`: Search in code or display text
|
||||
- `page`: Page number (default: 1)
|
||||
- `limit`: Items per page (default: 10)
|
||||
|
||||
### Get Statistics
|
||||
|
||||
```bash
|
||||
GET /icd/statistics
|
||||
```
|
||||
|
||||
Returns count statistics for ICD codes.
|
||||
|
||||
## Database Schema
|
||||
|
||||
The application uses PostgreSQL with Prisma ORM. The ICD codes are stored in the `icd_codes` table with the following structure:
|
||||
|
||||
```sql
|
||||
CREATE TABLE "icd_codes" (
|
||||
"id" TEXT PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
"code" TEXT UNIQUE NOT NULL,
|
||||
"display" TEXT NOT NULL,
|
||||
"version" TEXT NOT NULL,
|
||||
"category" TEXT NOT NULL, -- "ICD9" or "ICD10"
|
||||
"createdAt" TIMESTAMP DEFAULT NOW(),
|
||||
"updatedAt" TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
```
|
||||
|
||||
**ID Format**: The `id` field now uses UUID (Universal Unique Identifier) format like `550e8400-e29b-41d4-a716-446655440000` instead of CUID.
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
1. **Install Dependencies**
|
||||
### 1. Clone & Install
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd claim-guard-be
|
||||
npm install
|
||||
```
|
||||
|
||||
2. **Database Setup**
|
||||
Create a `.env` file with your PostgreSQL connection:
|
||||
### 2. Start Database
|
||||
|
||||
```bash
|
||||
DATABASE_URL="postgresql://username:password@localhost:5432/claim_guard_db?schema=public"
|
||||
# Start PostgreSQL with pgvector
|
||||
docker-compose up -d
|
||||
|
||||
# Verify database is running
|
||||
docker-compose ps
|
||||
```
|
||||
|
||||
3. **Generate Prisma Client**
|
||||
### 3. Setup Environment
|
||||
|
||||
```bash
|
||||
# Copy environment template (edit as needed)
|
||||
copy .env.example .env
|
||||
|
||||
# Update DATABASE_URL in .env:
|
||||
DATABASE_URL=postgresql://postgres:postgres123@localhost:5432/claim_guard
|
||||
```
|
||||
|
||||
### 4. Run Migrations
|
||||
|
||||
```bash
|
||||
# Apply database schema
|
||||
npx prisma migrate deploy
|
||||
|
||||
# Generate Prisma client
|
||||
npx prisma generate
|
||||
```
|
||||
|
||||
4. **Run Database Migrations**
|
||||
### 5. Start Application
|
||||
|
||||
```bash
|
||||
npx prisma db push
|
||||
# Development mode
|
||||
npm run start:dev
|
||||
|
||||
# Production mode
|
||||
npm run build
|
||||
npm run start:prod
|
||||
```
|
||||
|
||||
5. **Place Excel Files**
|
||||
Ensure the following files are in the `test/` directory:
|
||||
### 6. Access Services
|
||||
|
||||
- `[PUBLIC] ICD-9CM e-klaim.xlsx`
|
||||
- `[PUBLIC] ICD-10 e-klaim.xlsx`
|
||||
- **API**: http://localhost:3000
|
||||
- **Swagger Docs**: http://localhost:3000/docs
|
||||
- **Health Check**: http://localhost:3000/health
|
||||
|
||||
The Excel files should have at least 3 columns:
|
||||
## 📚 API Endpoints
|
||||
|
||||
- Column 1: Code
|
||||
- Column 2: Display/Description
|
||||
- Column 3: Version
|
||||
### ICD Management
|
||||
|
||||
## Project setup
|
||||
| Method | Endpoint | Description |
|
||||
| ------ | ----------------- | -------------------------------- |
|
||||
| `POST` | `/icd/import` | Import ICD data from Excel files |
|
||||
| `GET` | `/icd/search` | Search ICD codes with filters |
|
||||
| `GET` | `/icd/statistics` | Get database statistics |
|
||||
|
||||
### Health & Monitoring
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
| ------ | --------------- | ----------------------------- |
|
||||
| `GET` | `/health` | Application health check |
|
||||
| `GET` | `/health/ready` | Readiness probe |
|
||||
| `GET` | `/health/live` | Liveness probe |
|
||||
| `GET` | `/docs` | Interactive API documentation |
|
||||
|
||||
### Example Usage
|
||||
|
||||
```bash
|
||||
$ npm install
|
||||
# Import ICD data
|
||||
curl -X POST http://localhost:3000/icd/import
|
||||
|
||||
# Search for diabetes codes
|
||||
curl "http://localhost:3000/icd/search?search=diabetes&page=1&limit=10"
|
||||
|
||||
# Get statistics
|
||||
curl http://localhost:3000/icd/statistics
|
||||
|
||||
# Health check
|
||||
curl http://localhost:3000/health
|
||||
```
|
||||
|
||||
## Compile and run the project
|
||||
## 🐳 Docker Setup
|
||||
|
||||
### Database Only (Recommended)
|
||||
|
||||
```bash
|
||||
# development
|
||||
$ npm run start
|
||||
# Start PostgreSQL with pgvector
|
||||
docker-compose up -d
|
||||
|
||||
# watch mode
|
||||
$ npm run start:dev
|
||||
# Stop database
|
||||
docker-compose down
|
||||
|
||||
# production mode
|
||||
$ npm run start:prod
|
||||
# Reset database (deletes all data!)
|
||||
docker-compose down -v
|
||||
```
|
||||
|
||||
## Run tests
|
||||
### Connection Details
|
||||
|
||||
```env
|
||||
DATABASE_URL=postgresql://postgres:postgres123@localhost:5432/claim_guard
|
||||
Host: localhost
|
||||
Port: 5432
|
||||
Database: claim_guard
|
||||
Username: postgres
|
||||
Password: postgres123
|
||||
```
|
||||
|
||||
### Verify pgvector Extension
|
||||
|
||||
```bash
|
||||
# unit tests
|
||||
$ npm run test
|
||||
|
||||
# e2e tests
|
||||
$ npm run test:e2e
|
||||
|
||||
# test coverage
|
||||
$ npm run test:cov
|
||||
docker-compose exec postgres psql -U postgres -d claim_guard -c "SELECT name, default_version, installed_version FROM pg_available_extensions WHERE name = 'vector';"
|
||||
```
|
||||
|
||||
## Deployment
|
||||
## 🗂️ Database Schema
|
||||
|
||||
When you're ready to deploy your NestJS application to production, there are some key steps you can take to ensure it runs as efficiently as possible. Check out the [deployment documentation](https://docs.nestjs.com/deployment) for more information.
|
||||
### IcdCode Model
|
||||
|
||||
If you are looking for a cloud-based platform to deploy your NestJS application, check out [Mau](https://mau.nestjs.com), our official platform for deploying NestJS applications on AWS. Mau makes deployment straightforward and fast, requiring just a few simple steps:
|
||||
```prisma
|
||||
model IcdCode {
|
||||
id String @id @default(uuid())
|
||||
code String @unique
|
||||
display String
|
||||
version String
|
||||
category String // "ICD9" or "ICD10"
|
||||
createdAt DateTime @default(now())
|
||||
updatedAt DateTime @updatedAt
|
||||
|
||||
@@map("icd_codes")
|
||||
}
|
||||
```
|
||||
|
||||
### Migration Commands
|
||||
|
||||
```bash
|
||||
$ npm install -g @nestjs/mau
|
||||
$ mau deploy
|
||||
# Check migration status
|
||||
npx prisma migrate status
|
||||
|
||||
# Create new migration
|
||||
npx prisma migrate dev --name description
|
||||
|
||||
# Deploy to production
|
||||
npx prisma migrate deploy
|
||||
|
||||
# Reset database (development)
|
||||
npx prisma migrate reset
|
||||
```
|
||||
|
||||
With Mau, you can deploy your application in just a few clicks, allowing you to focus on building features rather than managing infrastructure.
|
||||
## ⚙️ Environment Configuration
|
||||
|
||||
## Resources
|
||||
### Development
|
||||
|
||||
Check out a few resources that may come in handy when working with NestJS:
|
||||
```env
|
||||
NODE_ENV=development
|
||||
PORT=3000
|
||||
DATABASE_URL=postgresql://postgres:postgres123@localhost:5432/claim_guard
|
||||
CORS_ORIGINS=http://localhost:3000,http://localhost:3001
|
||||
ENABLE_DOCS=true
|
||||
DEBUG=true
|
||||
LOG_LEVEL=debug
|
||||
```
|
||||
|
||||
- Visit the [NestJS Documentation](https://docs.nestjs.com) to learn more about the framework.
|
||||
- For questions and support, please visit our [Discord channel](https://discord.gg/G7Qnnhy).
|
||||
- To dive deeper and get more hands-on experience, check out our official video [courses](https://courses.nestjs.com/).
|
||||
- Deploy your application to AWS with the help of [NestJS Mau](https://mau.nestjs.com) in just a few clicks.
|
||||
- Visualize your application graph and interact with the NestJS application in real-time using [NestJS Devtools](https://devtools.nestjs.com).
|
||||
- Need help with your project (part-time to full-time)? Check out our official [enterprise support](https://enterprise.nestjs.com).
|
||||
- To stay in the loop and get updates, follow us on [X](https://x.com/nestframework) and [LinkedIn](https://linkedin.com/company/nestjs).
|
||||
- Looking for a job, or have a job to offer? Check out our official [Jobs board](https://jobs.nestjs.com).
|
||||
### Production
|
||||
|
||||
## Support
|
||||
```env
|
||||
NODE_ENV=production
|
||||
PORT=3000
|
||||
DATABASE_URL=postgresql://user:pass@host:5432/db
|
||||
CORS_ORIGINS=https://yourdomain.com
|
||||
ENABLE_DOCS=false
|
||||
DEBUG=false
|
||||
LOG_LEVEL=warn
|
||||
JWT_SECRET=strong-production-secret
|
||||
```
|
||||
|
||||
Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).
|
||||
### Available Variables
|
||||
|
||||
## Stay in touch
|
||||
| Variable | Description | Default |
|
||||
| -------------- | ---------------------------- | ----------------------- |
|
||||
| `NODE_ENV` | Environment mode | `development` |
|
||||
| `PORT` | Application port | `3000` |
|
||||
| `DATABASE_URL` | PostgreSQL connection string | Required |
|
||||
| `CORS_ORIGINS` | Allowed CORS origins | `http://localhost:3000` |
|
||||
| `ENABLE_DOCS` | Enable Swagger documentation | `true` |
|
||||
| `LOG_LEVEL` | Logging level | `info` |
|
||||
| `JWT_SECRET` | JWT signing secret | Required for auth |
|
||||
|
||||
- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)
|
||||
- Website - [https://nestjs.com](https://nestjs.com/)
|
||||
- Twitter - [@nestframework](https://twitter.com/nestframework)
|
||||
## 🧪 Testing
|
||||
|
||||
## License
|
||||
### API Testing
|
||||
|
||||
Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE).
|
||||
Use the included `icd.http` file with VS Code REST Client extension:
|
||||
|
||||
```http
|
||||
### Import ICD Data
|
||||
POST http://localhost:3000/icd/import
|
||||
|
||||
### Search ICD Codes
|
||||
GET http://localhost:3000/icd/search?search=diabetes&page=1&limit=10
|
||||
|
||||
### Get Statistics
|
||||
GET http://localhost:3000/icd/statistics
|
||||
```
|
||||
|
||||
### Unit Tests
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
npm run test
|
||||
|
||||
# Watch mode
|
||||
npm run test:watch
|
||||
|
||||
# Coverage
|
||||
npm run test:cov
|
||||
|
||||
# E2E tests
|
||||
npm run test:e2e
|
||||
```
|
||||
|
||||
## 🔧 Development
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── main.ts # Application entry point
|
||||
├── app.module.ts # Root module
|
||||
├── icd/ # ICD module
|
||||
│ ├── icd.controller.ts # REST endpoints
|
||||
│ ├── icd.service.ts # Business logic
|
||||
│ ├── icd.module.ts # Module definition
|
||||
│ └── dto/ # Data transfer objects
|
||||
├── health/ # Health check module
|
||||
└── prisma/ # Database schema
|
||||
```
|
||||
|
||||
### Scripts
|
||||
|
||||
```bash
|
||||
# Development
|
||||
npm run start:dev # Start with hot reload
|
||||
npm run start:debug # Start with debugger
|
||||
|
||||
# Build
|
||||
npm run build # Build for production
|
||||
npm run start:prod # Start production build
|
||||
|
||||
# Database
|
||||
npx prisma studio # Open Prisma Studio
|
||||
npx prisma db push # Push schema changes (dev only)
|
||||
npx prisma generate # Generate Prisma client
|
||||
|
||||
# Code Quality
|
||||
npm run lint # Run ESLint
|
||||
npm run format # Format with Prettier
|
||||
```
|
||||
|
||||
### Adding New Features
|
||||
|
||||
1. **Create DTOs** with validation decorators
|
||||
2. **Add Swagger decorators** for API documentation
|
||||
3. **Write unit tests** for services and controllers
|
||||
4. **Update database schema** if needed
|
||||
5. **Create migration** with descriptive name
|
||||
|
||||
## 📦 Deployment
|
||||
|
||||
### Docker Production
|
||||
|
||||
```dockerfile
|
||||
# Build stage
|
||||
FROM node:18-alpine AS builder
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci --only=production
|
||||
COPY . .
|
||||
RUN npm run build
|
||||
|
||||
# Production stage
|
||||
FROM node:18-alpine AS production
|
||||
WORKDIR /app
|
||||
COPY --from=builder /app/dist ./dist
|
||||
COPY --from=builder /app/node_modules ./node_modules
|
||||
COPY package*.json ./
|
||||
EXPOSE 3000
|
||||
CMD ["node", "dist/main"]
|
||||
```
|
||||
|
||||
### Environment Setup
|
||||
|
||||
1. **Production Database**: Use managed PostgreSQL (AWS RDS, Google Cloud SQL)
|
||||
2. **Environment Variables**: Set secure values for production
|
||||
3. **SSL/TLS**: Enable HTTPS in production
|
||||
4. **Monitoring**: Add application monitoring (Prometheus, Grafana)
|
||||
5. **Logging**: Configure centralized logging
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Port 5432 already in use:**
|
||||
|
||||
```bash
|
||||
# Check what's using the port
|
||||
netstat -ano | findstr :5432
|
||||
# Stop local PostgreSQL service
|
||||
```
|
||||
|
||||
**Database connection failed:**
|
||||
|
||||
```bash
|
||||
# Check if container is running
|
||||
docker-compose ps
|
||||
# Check logs
|
||||
docker-compose logs
|
||||
# Restart database
|
||||
docker-compose restart
|
||||
```
|
||||
|
||||
**Prisma can't connect:**
|
||||
|
||||
```bash
|
||||
# Verify DATABASE_URL in .env
|
||||
# Test connection
|
||||
npx prisma db pull
|
||||
```
|
||||
|
||||
**Build errors:**
|
||||
|
||||
```bash
|
||||
# Clean install
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
## 📄 License
|
||||
|
||||
This project is licensed under the MIT License.
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Add tests
|
||||
5. Submit a pull request
|
||||
|
||||
## 📞 Support
|
||||
|
||||
For questions and support:
|
||||
|
||||
- Check the [API documentation](http://localhost:3000/docs)
|
||||
- Review the troubleshooting section
|
||||
- Create an issue in the repository
|
||||
|
||||
---
|
||||
|
||||
**Ready to manage ICD codes efficiently!** 🚀
|
||||
|
||||
Reference in New Issue
Block a user