From e10126f7728efcca9f3a4d242078614657e13de7 Mon Sep 17 00:00:00 2001 From: ff Date: Mon, 13 Apr 2026 22:20:58 -0400 Subject: [PATCH] docs: rewrite README with complete step-by-step setup guide Adds ordered setup steps (Node.js, Python, Chrome, PostgreSQL, Redis, pip dependencies) so a fresh machine can be fully configured from git clone to running the app without guessing. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 160 +++++++++++++++++++++++++++--------------------------- 1 file changed, 80 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index c3b885c..1bfabc5 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,21 @@ +# Dental Manager - Starter + A monorepo setup to manage both Backend and Frontend of the Dental Manager application. -## Prerequisites +## 🖥️ Setup Guide (Fresh Machine) -Before running the project, make sure the following are installed on your machine: +Follow these steps in order after cloning the repository. -- **Node.js** v18+ -- **Python** 3.10+ -- **PostgreSQL** (primary database) -- **Redis** (job queue for Selenium and OCR tasks) +### Step 1 — Clone the repository -### Install Node.js (Ubuntu/Debian) +```sh +git clone +cd DentalManagementMHAprilgg +``` + +### Step 2 — Install Node.js + +Required to run the Backend and Frontend. ```sh curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - @@ -20,7 +26,9 @@ node -v # should print v20.x.x npm -v ``` -### Install Python (Ubuntu/Debian) +### Step 3 — Install Python + +Required to run the Selenium and OCR services. ```sh sudo apt-get install -y python3 python3-pip python3-venv @@ -29,21 +37,32 @@ sudo apt-get install -y python3 python3-pip python3-venv python3 --version # should print 3.10 or higher ``` -> The Selenium service also requires its Python dependencies. Install them once: -> ```sh -> cd apps/SeleniumService -> pip3 install -r requirements.txt -> ``` +### Step 4 — Install Chrome +Required for the Selenium service to control a browser. -### Install PostgreSQL (Ubuntu/Debian) +```sh +wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add - +echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list +sudo apt-get update +sudo apt-get install -y google-chrome-stable + +# Verify +google-chrome --version +``` + +> The `webdriver-manager` package (included in `requirements.txt`) automatically downloads the matching ChromeDriver — no manual driver setup needed. + +### Step 5 — Install PostgreSQL + +Primary database for the application. ```sh sudo apt-get install -y postgresql postgresql-contrib sudo systemctl enable postgresql sudo systemctl start postgresql -# Create a database and user (replace with your own values) +# Create a database and user (replace values as needed) sudo -u postgres psql -c "CREATE USER dental_user WITH PASSWORD 'yourpassword';" sudo -u postgres psql -c "CREATE DATABASE dental_db OWNER dental_user;" @@ -56,120 +75,101 @@ psql -U dental_user -d dental_db -c "\conninfo" > DATABASE_URL="postgresql://dental_user:yourpassword@localhost:5432/dental_db" > ``` -### Install Redis (Ubuntu/Debian) +### Step 6 — Install Redis + +Used as the job queue for Selenium and OCR background tasks. ```sh sudo apt-get install -y redis-server sudo systemctl enable redis-server sudo systemctl start redis-server -# Verify it's running +# Verify redis-cli ping # should print: PONG ``` -> Both PostgreSQL and Redis are system services, not npm packages. `npm install` handles all Node.js dependencies automatically — these must be installed separately at the OS level. +### Step 7 — Install Node.js dependencies - - - -# Dental Manager - Starter - -A monorepo setup to manage both Backend and Frontend of the Dental Manager application. - -## 🚀 Getting Started - -Follow the steps below to set up and run the project: - -1. Install dependency ```sh npm install ``` -2. Copy Environment Variables +### Step 8 — Install Python dependencies -Create `.env` files from the provided `.env.example` templates: -Change the required ones env in .env files. +Each Python service has its own dependencies: + +```sh +# Selenium automation service +cd apps/SeleniumService +pip3 install -r requirements.txt +cd ../.. + +# Payment OCR service +cd apps/PaymentOCRService +pip3 install -r requirements.txt +cd ../.. +``` + +### Step 9 — Set up environment variables + +Copy the `.env.example` files and fill in the required values. ```sh npm run setup:env ``` -3. Generate Prisma, and its Types. +### Step 10 — Set up the database -- Migrate the db: ```sh +# Run migrations npm run db:migrate -``` -- Generate the db types: -```sh +# Generate Prisma types npm run db:generate + +# Insert seed data +npm run db:seed ``` -- insert seed data -```sh -npm run db:seed +### Step 11 — Run the app -4. To Simply run all the app(Backend + Frontend). +Open two terminals: + +**Terminal 1** — Backend + Frontend: ```sh npm run dev ``` - -5. Now you need to run the selnium service as well in new terminal. -```sh +**Terminal 2** — Selenium service: +```sh cd apps/SeleniumService python3 agent.py ``` +--- + ## 📖 Developer Documentation - [Setting up server environment](docs/server-setup.md) — the first step, to run this app in environment. - [Development Hosts & Ports](docs/ports.md) — which app runs on which host/port +--- -## This in a Turborepo. What's inside? - -This Turborepo includes the following packages/apps: +## This is a Turborepo. What's inside? ### Apps and Packages -- `docs`: a [Next.js](https://nextjs.org/) app with [Tailwind CSS](https://tailwindcss.com/) -- `web`: another [Next.js](https://nextjs.org/) app with [Tailwind CSS](https://tailwindcss.com/) -- `ui`: a stub React component library with [Tailwind CSS](https://tailwindcss.com/) shared by both `web` and `docs` applications -- `@repo/eslint-config`: `eslint` configurations (includes `eslint-config-next` and `eslint-config-prettier`) -- `@repo/typescript-config`: `tsconfig.json`s used throughout the monorepo +- `apps/Backend` — Express.js API server +- `apps/Frontend` — React + Vite frontend +- `apps/SeleniumService` — Python FastAPI service for browser automation (insurance eligibility, claims) +- `apps/PaymentOCRService` — Python service for payment OCR extraction +- `@repo/eslint-config` — shared ESLint configuration +- `@repo/typescript-config` — shared `tsconfig.json`s -Each package/app is 100% [TypeScript](https://www.typescriptlang.org/). - -### Building packages/ui - -This example is set up to produce compiled styles for `ui` components into the `dist` directory. The component `.tsx` files are consumed by the Next.js apps directly using `transpilePackages` in `next.config.ts`. This was chosen for several reasons: - -- Make sharing one `tailwind.config.ts` to apps and packages as easy as possible. -- Make package compilation simple by only depending on the Next.js Compiler and `tailwindcss`. -- Ensure Tailwind classes do not overwrite each other. The `ui` package uses a `ui-` prefix for it's classes. -- Maintain clear package export boundaries. - -Another option is to consume `packages/ui` directly from source without building. If using this option, you will need to update the `tailwind.config.ts` in your apps to be aware of your package locations, so it can find all usages of the `tailwindcss` class names for CSS compilation. - -For example, in [tailwind.config.ts](packages/tailwind-config/tailwind.config.ts): - -```js - content: [ - // app content - `src/**/*.{js,ts,jsx,tsx}`, - // include packages if not transpiling - "../../packages/ui/*.{js,ts,jsx,tsx}", - ], -``` - -If you choose this strategy, you can remove the `tailwindcss` and `autoprefixer` dependencies from the `ui` package. +Each package/app is 100% [TypeScript](https://www.typescriptlang.org/) (except the Python services). ### Utilities -This Turborepo has some additional tools already setup for you: - - [Tailwind CSS](https://tailwindcss.com/) for styles - [TypeScript](https://www.typescriptlang.org/) for static type checking - [ESLint](https://eslint.org/) for code linting