improvement: fixed some package.json issues. readme files updated.

Reviewed-on: http://178.131.50.201:3000/admin/dyolink/pulls/9

.gitea/workflows/registry-build-deploy.yml

@@ -0,0 +1,146 @@
+# Build backend/frontend images, push to Gitea Container Registry, deploy with pull-only compose.
+#
+# Repository Variables (Settings → Actions → Variables) — non-secret:
+#   REGISTRY_HOST        e.g. 178.131.50.201:3000   (no http/https)
+#   REGISTRY_OWNER       Gitea user or org that owns the packages (same as image namespace)
+#   PUBLIC_BASE_URL      URL users open in browser, e.g. http://178.131.50.201:8088  (no trailing slash)
+#
+# Repository Secrets (Settings → Actions → Secrets):
+#   REGISTRY_USERNAME    Gitea username for docker login
+#   REGISTRY_PASSWORD    Gitea access token (packages:read/write) or account password
+#
+# Optional:
+#   STAGING_HTTP_PORT       host port for nginx (default 8088)
+#
+# Required for deploy job (absolute path on the runner host — forward slashes ok on Windows):
+#   DEPLOY_SECRETS_DIR      folder containing database.staging.env + backend.staging.env
+#
+# Runner: self-hosted with Docker; Git Bash recommended on Windows (shell: bash).
+#
+# We do NOT use gitea.com/actions/checkout — many restricted networks cannot reach gitea.com.
+# Checkout is a plain `git clone` from the same Gitea host (github.server_url / gitea alias).
+
+name: Registry — build, push, deploy
+
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  build-and-push:
+    runs-on: self-hosted
+    outputs:
+      image_tag: ${{ steps.meta.outputs.image_tag }}
+    steps:
+      - name: Checkout (clone from this Gitea — no gitea.com)
+        run: |
+          set -e
+          SERVER="${{ github.server_url }}"
+          SERVER="${SERVER%/}"
+          REPO="${{ github.repository }}"
+          BRANCH="${{ github.ref_name }}"
+          TOKEN="${{ github.token }}"
+          ACTOR="${{ github.actor }}"
+          HP="${SERVER#http://}"
+          HP="${HP#https://}"
+          if [[ "$SERVER" == https://* ]]; then
+            CLONE_URL="https://${ACTOR}:${TOKEN}@${HP}/${REPO}.git"
+          else
+            CLONE_URL="http://${ACTOR}:${TOKEN}@${HP}/${REPO}.git"
+          fi
+          GIT_TERMINAL_PROMPT=0 git clone --depth 1 --branch "$BRANCH" "$CLONE_URL" .
+
+      - name: Image tag and registry prefix
+        id: meta
+        run: |
+          echo "image_tag=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
+          echo "REGISTRY_PREFIX=${{ vars.REGISTRY_HOST }}/${{ vars.REGISTRY_OWNER }}" >> "$GITHUB_ENV"
+
+      - name: Log in to container registry
+        run: |
+          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login "${{ vars.REGISTRY_HOST }}" \
+            -u "${{ secrets.REGISTRY_USERNAME }}" --password-stdin
+
+      - name: Build and push backend
+        run: |
+          TAG="${{ steps.meta.outputs.image_tag }}"
+          docker build \
+            -t "${REGISTRY_PREFIX}/dyolink-backend:${TAG}" \
+            -t "${REGISTRY_PREFIX}/dyolink-backend:latest" \
+            ./backend
+          docker push "${REGISTRY_PREFIX}/dyolink-backend:${TAG}"
+          docker push "${REGISTRY_PREFIX}/dyolink-backend:latest"
+
+      - name: Build and push frontend
+        env:
+          PUBLIC_BASE_URL: ${{ vars.PUBLIC_BASE_URL }}
+        run: |
+          TAG="${{ steps.meta.outputs.image_tag }}"
+          docker build \
+            --build-arg NEXT_PUBLIC_API_URL="${PUBLIC_BASE_URL}/api" \
+            --build-arg NEXT_PUBLIC_APP_URL="${PUBLIC_BASE_URL}" \
+            --build-arg NEXT_PUBLIC_APP_NAME="Dyolink" \
+            -t "${REGISTRY_PREFIX}/dyolink-frontend:${TAG}" \
+            -t "${REGISTRY_PREFIX}/dyolink-frontend:latest" \
+            ./frontend
+          docker push "${REGISTRY_PREFIX}/dyolink-frontend:${TAG}"
+          docker push "${REGISTRY_PREFIX}/dyolink-frontend:latest"
+
+  deploy:
+    needs: build-and-push
+    runs-on: self-hosted
+    steps:
+      - name: Checkout (shallow clone from this Gitea — no gitea.com)
+        run: |
+          set -e
+          SERVER="${{ github.server_url }}"
+          SERVER="${SERVER%/}"
+          REPO="${{ github.repository }}"
+          BRANCH="${{ github.ref_name }}"
+          TOKEN="${{ github.token }}"
+          ACTOR="${{ github.actor }}"
+          HP="${SERVER#http://}"
+          HP="${HP#https://}"
+          if [[ "$SERVER" == https://* ]]; then
+            CLONE_URL="https://${ACTOR}:${TOKEN}@${HP}/${REPO}.git"
+          else
+            CLONE_URL="http://${ACTOR}:${TOKEN}@${HP}/${REPO}.git"
+          fi
+          GIT_TERMINAL_PROMPT=0 git clone --depth 1 --branch "$BRANCH" "$CLONE_URL" .
+
+      - name: Write deploy.registry.env and validate secrets path
+        run: |
+          SD='${{ vars.DEPLOY_SECRETS_DIR }}'
+          if [ -z "$SD" ]; then
+            echo "Set repository variable DEPLOY_SECRETS_DIR to the absolute path on this runner"
+            echo "where database.staging.env and backend.staging.env live (not in git)."
+            exit 1
+          fi
+          test -f "${SD}/database.staging.env" || { echo "Missing ${SD}/database.staging.env"; exit 1; }
+          test -f "${SD}/backend.staging.env" || { echo "Missing ${SD}/backend.staging.env"; exit 1; }
+          cd infrastructure
+          STAGING_PORT='${{ vars.STAGING_HTTP_PORT }}'
+          STAGING_PORT="${STAGING_PORT:-8088}"
+          {
+            echo "REGISTRY_PREFIX=${{ vars.REGISTRY_HOST }}/${{ vars.REGISTRY_OWNER }}"
+            echo "IMAGE_TAG=${{ needs.build-and-push.outputs.image_tag }}"
+            echo "STAGING_HTTP_PORT=${STAGING_PORT}"
+            echo "DEPLOY_SECRETS_DIR=${SD}"
+          } > deploy.registry.env
+
+      - name: Log in to container registry (for pull)
+        run: |
+          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login "${{ vars.REGISTRY_HOST }}" \
+            -u "${{ secrets.REGISTRY_USERNAME }}" --password-stdin
+
+      - name: Pull and start stack
+        run: |
+          set -e
+          cd infrastructure
+          docker compose -f docker-compose.registry.yml --env-file deploy.registry.env pull backend frontend
+          docker compose -f docker-compose.registry.yml --env-file deploy.registry.env up -d

.gitignore

@@ -5,7 +5,6 @@ node_modules/
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
-package-lock.json
 yarn.lock
 
 # === Build outputs ===
@@ -82,8 +81,10 @@ secrets/
 *.db
 *.sqlite3
 
-# === Gitea specific ===
-.gitea/
+# === Gitea specific (keep Actions workflows; ignore other local .gitea noise) ===
+.gitea/*
+!.gitea/workflows
+!.gitea/workflows/**
 
 # Prisma generated files
 prisma/*.db

README.md

@@ -0,0 +1,115 @@
+# Dyolink
+
+Monorepo: **NestJS** backend (`backend/`), **Next.js** frontend (`frontend/`), **Docker** stack under `infrastructure/`.
+
+Local development: see **`backend/README.md`** and **`frontend/README.md`**.
+
+---
+
+## Deploy on your own server (Docker + Gitea)
+
+High level: **build container images → push to a registry → server pulls images and runs Compose**. Optionally **Gitea Actions** automates that on every merge to `main` / `master`.
+
+### 1. One-time server preparation
+
+1. Install **Docker** and **Docker Compose** on the server.
+2. Run **Gitea** with the **container registry** enabled (same host/port you use for `docker login`, e.g. `178.131.50.201:3000`).
+3. Copy the repo (or deploy only `infrastructure/` + secrets). You need at least:
+
+   - `infrastructure/docker-compose.registry.yml`
+   - `infrastructure/nginx/` configs referenced by that compose file
+   - `infrastructure/database/init.sql` if used by your Postgres service
+
+4. **Secrets on the server** (never commit real values):
+
+   - Copy `infrastructure/database.staging.env.example` → **`database.staging.env`** (Postgres user/password/db).
+   - Copy `infrastructure/backend.staging.env.example` → **`backend.staging.env`** (e.g. `DATABASE_URL`, JWT, pointing at the compose Postgres service name).
+   - Put both files in one directory on the server, e.g. `/opt/dyolink/secrets/`.
+
+5. **Registry login from the server** (same credentials you use for `docker push`):
+
+   ```bash
+   docker login <registry-host>:<port> -u <user>
+   ```
+
+   For HTTP registries, Docker may require **`insecure-registries`** on the daemon.
+
+### 2. Manual deploy (build images elsewhere, run on server)
+
+On your **dev machine** (after successful local builds):
+
+```powershell
+$REG = "<registry-host>:<port>"
+$OWN = "<registry-owner>"
+$TAG = "manual"
+
+docker build -t "${REG}/${OWN}/dyolink-backend:${TAG}" -t "${REG}/${OWN}/dyolink-backend:latest" ./backend
+
+docker build `
+  --build-arg NEXT_PUBLIC_API_URL="http://<your-public-ip>:<nginx-port>/api" `
+  --build-arg NEXT_PUBLIC_APP_URL="http://<your-public-ip>:<nginx-port>" `
+  --build-arg NEXT_PUBLIC_APP_NAME="Dyolink" `
+  -t "${REG}/${OWN}/dyolink-frontend:${TAG}" `
+  -t "${REG}/${OWN}/dyolink-frontend:latest" `
+  ./frontend
+
+docker push "${REG}/${OWN}/dyolink-backend:${TAG}"
+docker push "${REG}/${OWN}/dyolink-backend:latest"
+docker push "${REG}/${OWN}/dyolink-frontend:${TAG}"
+docker push "${REG}/${OWN}/dyolink-frontend:latest"
+```
+
+On the **server**, from `infrastructure/`:
+
+1. Create **`deploy.registry.env`** (see `infrastructure/deploy.registry.env.example`):
+
+   - `REGISTRY_PREFIX=<host>:<port>/<owner>` (no `http://`, no trailing slash)
+   - `IMAGE_TAG=latest` or the tag you pushed
+   - `STAGING_HTTP_PORT=<host port>` (e.g. `8088` — browser uses `http://<ip>:8088`)
+
+2. Set **`DEPLOY_SECRETS_DIR`** to the absolute path of the folder containing `database.staging.env` and `backend.staging.env` (you can export it in the shell or add it to `deploy.registry.env` if your Compose setup expects it).
+
+3. Pull and start:
+
+   ```bash
+   docker compose -f docker-compose.registry.yml --env-file deploy.registry.env pull backend frontend
+   docker compose -f docker-compose.registry.yml --env-file deploy.registry.env up -d
+   ```
+
+The backend container runs **`prisma migrate deploy`** on startup (via entrypoint) when `NODE_ENV=production`, so schema updates apply after you deploy a new image that includes new migrations.
+
+### 3. Automatic deploy (Gitea Actions)
+
+Workflow file: **`.gitea/workflows/registry-build-deploy.yml`**.
+
+**Requirements:**
+
+- **Gitea Actions** enabled for the repository.
+- A **self-hosted runner** (with Docker) registered to Gitea — the workflow uses `runs-on: self-hosted`.
+- **Repository → Actions → Variables** (examples):
+
+  - `REGISTRY_HOST` — e.g. `178.131.50.201:3000`
+  - `REGISTRY_OWNER` — image namespace (same as Docker image path after the host), e.g. `admin`
+  - `PUBLIC_BASE_URL` — URL users open in the browser, e.g. `http://178.131.50.201:8088` (no trailing slash)
+  - `DEPLOY_SECRETS_DIR` — **absolute path on the runner machine** to the folder containing `database.staging.env` and `backend.staging.env`
+  - Optional: `STAGING_HTTP_PORT` (defaults to `8088`)
+
+- **Repository → Actions → Secrets:**
+
+  - `REGISTRY_USERNAME`
+  - `REGISTRY_PASSWORD` — access token with package read/write (or equivalent)
+
+**Trigger:** push to **`main`** or **`master`**, or run the workflow manually (**workflow_dispatch**).
+
+The pipeline clones from your Gitea instance, builds and pushes backend/frontend images, then on the runner runs **`docker compose pull`** and **`up -d`** using `infrastructure/docker-compose.registry.yml`.
+
+---
+
+## Related paths
+
+| Path | Role |
+|------|------|
+| `backend/Dockerfile` | API image |
+| `frontend/Dockerfile` | Web image |
+| `infrastructure/docker-compose.registry.yml` | Pull-only staging stack (registry images + nginx + postgres) |
+| `infrastructure/deploy.registry.env.example` | Template for `deploy.registry.env` |

backend/.npmrc

@@ -0,0 +1 @@
+legacy-peer-deps=true

backend/Dockerfile

@@ -1,92 +1,55 @@
 # ============================================
 # STAGE 1: BUILDER STAGE
 # ============================================
-# This stage builds the application and prepares assets
-FROM node:18-alpine AS builder
+FROM node:20-alpine AS builder
 
-# Set working directory
 WORKDIR /app
 
-# Copy package.json and package-lock.json first (for better caching)
 COPY package*.json ./
-
-# Copy Prisma schema (needed for Prisma client generation)
+COPY .npmrc ./
 COPY prisma ./prisma/
 
-# Install ALL dependencies (including dev dependencies for build)
 RUN npm ci
 
-# Copy source code
 COPY . .
 
-# Generate Prisma client
-RUN npx prisma generate
-
-# Build the NestJS application
+RUN npm run prisma:generate
 RUN npm run build
-
-# Remove development dependencies to reduce size
 RUN npm prune --production
 
 
 # ============================================
 # STAGE 2: PRODUCTION STAGE
 # ============================================
-# This stage creates the final production image
-FROM node:18-alpine
+FROM node:20-alpine
 
-# Install dumb-init for proper signal handling
 RUN apk add --no-cache dumb-init
 
-# Set working directory
 WORKDIR /app
 
-# Create non-root user for security
 RUN addgroup -g 1001 -S nodejs && \
     adduser -S dyolink -u 1001
 
-# Copy package.json files
+# Prisma client comes from the builder (npm prune --production keeps @prisma/client).
 COPY package*.json ./
-
-# Copy Prisma schema
 COPY prisma ./prisma/
 
-# Install ONLY production dependencies
-RUN npm ci --only=production && \
-    npm cache clean --force
-
-# Generate Prisma client in production
-RUN npx prisma generate
-
-# Copy built application from builder stage
 COPY --from=builder /app/dist ./dist
-
-# Copy node_modules (already pruned)
 COPY --from=builder /app/node_modules ./node_modules
 
-# Create necessary directories with proper permissions
+COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+
 RUN mkdir -p /app/logs && \
     chown -R dyolink:nodejs /app
 
-# Set ownership of all files to non-root user
-RUN chown -R dyolink:nodejs /app
-
-# Switch to non-root user
 USER dyolink
 
-# Expose the application port
 EXPOSE 3000
 
-# Health check configuration
 HEALTHCHECK --interval=30s --timeout=5s --start-period=40s --retries=3 \
-  CMD node -e "require('http').get('http://localhost:3000/api/health', (r) => {if(r.statusCode!==200)throw new Error()})" || exit 1
+  CMD node -e "require('http').get('http://127.0.0.1:3000/api/health', (r) => {if(r.statusCode!==200)process.exit(1)})"
 
-# Copy entrypoint script
-COPY docker-entrypoint.sh /usr/local/bin/
-RUN chmod +x /usr/local/bin/docker-entrypoint.sh
-
-# Use dumb-init to properly handle signals
 ENTRYPOINT ["dumb-init", "--", "docker-entrypoint.sh"]
 
-# Start the application
-CMD ["node", "dist/main"]
+CMD ["node", "dist/main"]

backend/README.md

@@ -1,98 +1,88 @@
-<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>
+# Dyolink — Backend (NestJS)
 
-[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456
-[circleci-url]: https://circleci.com/gh/nestjs/nest
+## Prerequisites
 
-  <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>
-  <!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
-  [![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->
+- **Node.js 20+** and **npm**
+- **PostgreSQL** reachable from your machine (local or remote)
 
-## Description
+## First-time setup
 
-[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository.
+1. **Clone the monorepo** and go to the backend app:
 
-## Project setup
+   ```bash
+   git clone <repository-url> dyolink
+   cd dyolink/backend
+   ```
+
+2. **Install dependencies**
+
+   ```bash
+   npm install
+   ```
+
+3. **Environment**
+
+   Copy `.env.example` to `.env` and set at least:
+
+   - `DATABASE_URL` — PostgreSQL connection string for your dev database
+   - `JWT_SECRET` — strong secret for signing tokens  
+   Do not commit `.env`.
+
+4. **Database URL for local dev**
+
+   Point `DATABASE_URL` at a database you created in Postgres (create an empty DB first if needed).
+
+5. **Generate Prisma Client**
+
+   ```bash
+   npm run prisma:generate
+   ```
+
+6. **Apply migrations** (creates/updates tables to match `prisma/schema.prisma`)
+
+   ```bash
+   npm run prisma:migrate
+   ```
+
+   This runs `prisma migrate dev`. Use it during development when the schema changes.
+
+7. **Seed** (optional — sample data / bootstrap)
+
+   ```bash
+   npm run prisma:seed
+   ```
+
+## Run (development)
 
 ```bash
-$ npm install
+npm run start:dev
 ```
 
-## Compile and run the project
+API listens on **`http://localhost:3000`** by default (`PORT` in `.env`).
+
+If the frontend runs on another origin (e.g. `http://localhost:3001`), set `CORS_ORIGIN` in `.env` to that URL.
+
+## After pulling latest `main`
 
 ```bash
-# development
-$ npm run start
-
-# watch mode
-$ npm run start:dev
-
-# production mode
-$ npm run start:prod
+git pull
+npm install
+npm run prisma:generate
+npm run prisma:migrate
 ```
 
-## Run tests
+If teammates added migrations, step 4 applies them. Resolve migration conflicts locally before pushing.
 
-```bash
-# unit tests
-$ npm run test
+## Useful commands
 
-# e2e tests
-$ npm run test:e2e
+| Command | Purpose |
+|--------|---------|
+| `npm run prisma:generate` | Regenerate client after `schema.prisma` changes |
+| `npm run prisma:migrate` | Dev migrations (`migrate dev`) |
+| `npm run prisma:deploy` | Production-style apply (`migrate deploy`) — e.g. CI/containers |
+| `npm run build` | Compile Nest app |
+| `npm run start:prod` | Run compiled app (`node dist/main`) |
 
-# test coverage
-$ npm run test:cov
-```
+## Docker
 
-## Deployment
-
-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.
-
-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:
-
-```bash
-$ npm install -g @nestjs/mau
-$ mau deploy
-```
-
-With Mau, you can deploy your application in just a few clicks, allowing you to focus on building features rather than managing infrastructure.
-
-## Resources
-
-Check out a few resources that may come in handy when working with NestJS:
-
-- 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).
-
-## Support
-
-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).
-
-## Stay in touch
-
-- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)
-- Website - [https://nestjs.com](https://nestjs.com/)
-- Twitter - [@nestframework](https://twitter.com/nestframework)
-
-## License
-
-Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE).
+Image build is defined in **`Dockerfile`** at this folder. For full-stack deployment and CI, see the **repository root `README.md`**.

backend/SETUP.md

@@ -1,95 +0,0 @@
-
-# Dyolink Backend - Development Setup Guide
-
-## 📋 Prerequisites
-
-Before starting, ensure you have the following installed:
-- **Node.js** (v18 or higher)
-- **PostgreSQL** (v15 or higher) - We use v18, but any v15+ works
-- **Git** (for cloning)
-- **npm** or **yarn** (npm comes with Node.js)
-
-## 🚀 Initial Setup Steps
-
-1. Clone the Repository
-```bash
-git clone [your-repository-url]
-cd dyolink/backend
-
-2. Install Dependencies
-bash
-npm install
-
-3. Environment Configuration
-Create a .env file in the backend folder:
-env
-# backend/.env
-DATABASE_URL=postgresql://postgres:1234@localhost:5432/dyolink_db
-JWT_SECRET=your-super-secret-key-here-change-this
-JWT_REFRESH_SECRET=your-super-secret-refresh-key-here-different-from-above
-JWT_EXPIRES_IN=15m
-JWT_REFRESH_EXPIRES_IN=7d
-PORT=3000
-⚠️ Important: Never commit the .env file to git! We have .gitignore set up to prevent this.
-
-4. Database Setup
-Option A: Fresh PostgreSQL Installation
-If you don't have PostgreSQL installed:
-Windows (using Chocolatey):
-bash
-choco install postgresql
-macOS (using Homebrew):
-bash
-brew install postgresql@15
-brew services start postgresql@15
-Common Installation Issues & Fixes:
-Issue	Solution
-"Password not set during installation"	Edit pg_hba.conf temporarily (see Troubleshooting section)
-"Service not starting"	Run PowerShell/Terminal as Administrator
-"Port 5432 already in use"	Stop local PostgreSQL service or change port
-Option B: Using Existing PostgreSQL
-If you already have PostgreSQL:
-bash
-# Connect to PostgreSQL
-psql -U postgres
-# Create the database (if it doesn't exist)
-CREATE DATABASE dyolink_db;
-\q
-
-5. Database Migrations
-Once PostgreSQL is running and you've created the database:
-bash
-# Generate Prisma client
-npx prisma generate
-# Run migrations to create tables
-npx prisma migrate dev --name init_schema
-⚠️ Known Issue: If you get P1001: Can't reach database server, ensure PostgreSQL is running:
-bash
-# Check PostgreSQL status
-# Windows:
-Get-Service postgresql-x64-18
-# macOS:
-brew services list | grep postgres
-
-6. Seed the Database
-bash
-# Seed with initial data (organization types, plans, permissions, test user)
-npx prisma db seed
-⚠️ Prisma 7 Note: If seeding fails with PrismaClientInitializationError, we've fixed this by using the driver adapter pattern. The seed file now uses:
-typescript
-import { PrismaPg } from '@prisma/adapter-pg';
-import { Pool } from 'pg';
-const adapter = new PrismaPg(pool);
-const prisma = new PrismaClient({ adapter });
-7. Verify Setup
-bash
-# Open Prisma Studio to verify data
-npx prisma studio
-# This opens http://localhost:5555 - you should see all tables with seeded data
-8. Start Development Server
-bash
-npm run start:dev
-You should see:
-text
-Application is running on: http://localhost:3000
-✅ Database connected successfully

backend/docker-entrypoint.sh

@@ -1,76 +1,36 @@
 #!/bin/sh
 set -e
 
-# ============================================
-# DOCKER ENTRYPOINT SCRIPT
-# This script runs BEFORE the application starts
-# ============================================
+echo "=========================================="
+echo "  Dyolink Backend - Docker Entrypoint"
+echo "=========================================="
 
-# Colors for logging (optional, for better readability)
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-echo "${GREEN}========================================${NC}"
-echo "${GREEN}  Dyolink Backend - Docker Entrypoint  ${NC}"
-echo "${GREEN}========================================${NC}"
-
-# Check if we're in development or production
 if [ "$NODE_ENV" = "production" ]; then
-    echo "${GREEN}Running in PRODUCTION mode${NC}"
-    
-    # Run database migrations
-    echo "${YELLOW}Running database migrations...${NC}"
-    npx prisma migrate deploy
-    
-    # Check if migrations were successful
-    if [ $? -eq 0 ]; then
-        echo "${GREEN}✓ Database migrations completed successfully${NC}"
-    else
-        echo "${RED}✗ Database migrations failed!${NC}"
-        exit 1
-    fi
+    echo "Running in PRODUCTION mode"
+    echo "Running database migrations..."
+    ./node_modules/.bin/prisma migrate deploy
 else
-    echo "${YELLOW}Running in DEVELOPMENT mode${NC}"
-    
-    # In development, we might want to push schema instead of migrations
-    echo "${YELLOW}Syncing database schema...${NC}"
-    npx prisma db push
-    
-    if [ $? -eq 0 ]; then
-        echo "${GREEN}✓ Database schema synced successfully${NC}"
-    else
-        echo "${RED}✗ Database schema sync failed!${NC}"
-        exit 1
+    echo "Running in DEVELOPMENT mode"
+    echo "Syncing database schema..."
+    ./node_modules/.bin/prisma db push
+fi
+
+if [ "$NODE_ENV" != "production" ]; then
+    if [ -f "prisma/seed.ts" ] || [ -f "prisma/seed.js" ]; then
+        echo "Running database seed..."
+        ./node_modules/.bin/prisma db seed
     fi
 fi
 
-# Optional: Run seed script if it exists and NODE_ENV is not production
-if [ "$NODE_ENV" != "production" ] && [ -f "prisma/seed.js" ]; then
-    echo "${YELLOW}Running database seed...${NC}"
-    npx prisma db seed
-    echo "${GREEN}✓ Database seeded successfully${NC}"
-fi
-
-# Verify database connection
-echo "${YELLOW}Verifying database connection...${NC}"
-npx prisma db execute --file /dev/null --schema prisma/schema.prisma 2>/dev/null
-
-if [ $? -eq 0 ]; then
-    echo "${GREEN}✓ Database connection verified${NC}"
-else
-    echo "${RED}✗ Cannot connect to database!${NC}"
+echo "Verifying database connection..."
+if ! echo "SELECT 1" | ./node_modules/.bin/prisma db execute --stdin --schema prisma/schema.prisma >/dev/null 2>&1; then
+    echo "Cannot connect to database or execute query."
     exit 1
 fi
+echo "Database connection OK"
 
-# Print application information
-echo "${GREEN}========================================${NC}"
-echo "${GREEN}Starting Dyolink Backend Application...${NC}"
-echo "${GREEN}  • Environment: ${NODE_ENV:-development}${NC}"
-echo "${GREEN}  • Port: ${PORT:-3000}${NC}"
-echo "${GREEN}  • Database: ${DATABASE_URL%%@*}@***${NC}"
-echo "${GREEN}========================================${NC}"
+echo "Starting Dyolink Backend..."
+echo "  Environment: ${NODE_ENV:-development}"
+echo "  Port: ${PORT:-3000}"
 
-# Execute the main command (passed as CMD)
-exec "$@"
+exec "$@"

backend/package.json

@@ -41,6 +41,7 @@
     "@nestjs/swagger": "^11.2.6",
     "@nestjs/throttler": "^6.5.0",
     "@prisma/client": "^6.19.2",
+    "prisma": "^6.19.2",
     "adminjs": "^7.8.17",
     "axios": "^1.13.5",
     "bcrypt": "^6.0.0",
@@ -84,7 +85,6 @@
     "globals": "^16.0.0",
     "jest": "^30.0.0",
     "prettier": "^3.4.2",
-    "prisma": "^6.19.2",
     "source-map-support": "^0.5.21",
     "supertest": "^7.0.0",
     "ts-jest": "^29.2.5",
@@ -94,6 +94,10 @@
     "typescript": "^5.7.3",
     "typescript-eslint": "^8.20.0"
   },
+  "overrides": {
+    "@tiptap/core": "2.27.2",
+    "@tiptap/pm": "2.27.2"
+  },
   "jest": {
     "moduleFileExtensions": [
       "js",

backend/prisma/migrations/20260429090959_add_patients_feature/migration.sql

@@ -0,0 +1,47 @@
+-- CreateTable
+CREATE TABLE "patients" (
+    "id" TEXT NOT NULL,
+    "organizationId" TEXT NOT NULL,
+    "firstName" TEXT NOT NULL,
+    "lastName" TEXT NOT NULL,
+    "phone" TEXT,
+    "email" TEXT,
+    "dateOfBirth" TIMESTAMP(3),
+    "notes" TEXT,
+    "isActive" BOOLEAN NOT NULL DEFAULT true,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "patients_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "patient_treatment_histories" (
+    "id" TEXT NOT NULL,
+    "patientId" TEXT NOT NULL,
+    "title" TEXT NOT NULL,
+    "status" TEXT NOT NULL,
+    "treatmentAt" TIMESTAMP(3) NOT NULL,
+    "tooth" TEXT,
+    "notes" TEXT,
+    "totalCost" DOUBLE PRECISION,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "patient_treatment_histories_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "patients_organizationId_createdAt_idx" ON "patients"("organizationId", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "patients_organizationId_lastName_firstName_idx" ON "patients"("organizationId", "lastName", "firstName");
+
+-- CreateIndex
+CREATE INDEX "patient_treatment_histories_patientId_treatmentAt_idx" ON "patient_treatment_histories"("patientId", "treatmentAt");
+
+-- AddForeignKey
+ALTER TABLE "patients" ADD CONSTRAINT "patients_organizationId_fkey" FOREIGN KEY ("organizationId") REFERENCES "organizations"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "patient_treatment_histories" ADD CONSTRAINT "patient_treatment_histories_patientId_fkey" FOREIGN KEY ("patientId") REFERENCES "patients"("id") ON DELETE CASCADE ON UPDATE CASCADE;

backend/prisma/migrations/20260429134000_add_user_trial_used_at/migration.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "users"
+ADD COLUMN "trialUsedAt" TIMESTAMP(3);

backend/prisma/migrations/20260430091832_staff_invites_activation/migration.sql

@@ -0,0 +1,29 @@
+-- AlterTable
+ALTER TABLE "memberships" ADD COLUMN     "isActive" BOOLEAN NOT NULL DEFAULT true;
+
+-- CreateTable
+CREATE TABLE "staff_invitations" (
+    "id" TEXT NOT NULL,
+    "membershipId" TEXT NOT NULL,
+    "invitedById" TEXT NOT NULL,
+    "tokenHash" TEXT NOT NULL,
+    "expiresAt" TIMESTAMP(3) NOT NULL,
+    "acceptedAt" TIMESTAMP(3),
+    "revokedAt" TIMESTAMP(3),
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "staff_invitations_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "staff_invitations_tokenHash_key" ON "staff_invitations"("tokenHash");
+
+-- CreateIndex
+CREATE INDEX "staff_invitations_membershipId_createdAt_idx" ON "staff_invitations"("membershipId", "createdAt");
+
+-- AddForeignKey
+ALTER TABLE "staff_invitations" ADD CONSTRAINT "staff_invitations_membershipId_fkey" FOREIGN KEY ("membershipId") REFERENCES "memberships"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "staff_invitations" ADD CONSTRAINT "staff_invitations_invitedById_fkey" FOREIGN KEY ("invitedById") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;

backend/prisma/migrations/20260430134958/migration.sql

@@ -0,0 +1,5 @@
+-- DropForeignKey
+ALTER TABLE "organizations" DROP CONSTRAINT "organizations_planId_fkey";
+
+-- AddForeignKey
+ALTER TABLE "organizations" ADD CONSTRAINT "organizations_planId_fkey" FOREIGN KEY ("planId") REFERENCES "plans"("id") ON DELETE SET NULL ON UPDATE CASCADE;

backend/prisma/migrations/20260430135000_make_organization_plan_optional/migration.sql

@@ -0,0 +1,3 @@
+-- Allow organizations without an active subscription plan.
+ALTER TABLE "organizations"
+ALTER COLUMN "planId" DROP NOT NULL;

backend/prisma/migrations/20260430184000_add_treatment_permissions/migration.sql

@@ -0,0 +1,24 @@
+-- Ensure Treatment feature and permissions exist for existing databases.
+WITH treatment_feature AS (
+  INSERT INTO "features" ("id", "name")
+  VALUES (md5(random()::text || clock_timestamp()::text), 'Treatment')
+  ON CONFLICT ("name") DO UPDATE SET "name" = EXCLUDED."name"
+  RETURNING "id"
+),
+selected_feature AS (
+  SELECT "id" FROM treatment_feature
+  UNION ALL
+  SELECT f."id" FROM "features" f WHERE f."name" = 'Treatment' LIMIT 1
+)
+INSERT INTO "permissions" ("id", "name", "featureId")
+SELECT md5(random()::text || clock_timestamp()::text), 'TAB_TREATMENT_READ', sf."id"
+FROM selected_feature sf
+ON CONFLICT ("name") DO NOTHING;
+
+WITH treatment_feature AS (
+  SELECT "id" FROM "features" WHERE "name" = 'Treatment' LIMIT 1
+)
+INSERT INTO "permissions" ("id", "name", "featureId")
+SELECT md5(random()::text || clock_timestamp()::text), 'TAB_TREATMENT_EDIT', tf."id"
+FROM treatment_feature tf
+ON CONFLICT ("name") DO NOTHING;

backend/prisma/schema.prisma

@@ -15,10 +15,12 @@ model User {
   googleId     String? @unique
   facebookId   String? @unique
   name         String
+  trialUsedAt  DateTime?
 
   memberships        Membership[]
   ownedOrganizations Organization[] @relation("OrganizationOwner")
   sessions           Session[] // 👈 ADD THIS - opposite relation for Session
+  sentStaffInvites   StaffInvitation[]
 
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
@@ -50,11 +52,12 @@ model Organization {
   owner   User   @relation("OrganizationOwner", fields: [ownerId], references: [id])
 
   memberships Membership[]
-  planId      String
-  plan        Plan         @relation(fields: [planId], references: [id])
+  planId      String?
+  plan        Plan?        @relation(fields: [planId], references: [id])
 
   sharedWithMe     OrganizationLink[] @relation("OrganizationB")
   sharedWithOthers OrganizationLink[] @relation("OrganizationA")
+  patients         Patient[]
 
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
@@ -62,6 +65,45 @@ model Organization {
   @@map("organizations")
 }
 
+model Patient {
+  id             String   @id @default(uuid())
+  organizationId String
+  firstName      String
+  lastName       String
+  phone          String?
+  email          String?
+  dateOfBirth    DateTime?
+  notes          String?
+  isActive       Boolean  @default(true)
+  createdAt      DateTime @default(now())
+  updatedAt      DateTime @updatedAt
+
+  organization Organization             @relation(fields: [organizationId], references: [id])
+  treatments   PatientTreatmentHistory[]
+
+  @@index([organizationId, createdAt])
+  @@index([organizationId, lastName, firstName])
+  @@map("patients")
+}
+
+model PatientTreatmentHistory {
+  id          String   @id @default(uuid())
+  patientId   String
+  title       String
+  status      String
+  treatmentAt DateTime
+  tooth       String?
+  notes       String?
+  totalCost   Float?
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  patient Patient @relation(fields: [patientId], references: [id], onDelete: Cascade)
+
+  @@index([patientId, treatmentAt])
+  @@map("patient_treatment_histories")
+}
+
 model Plan {
   id       String @id @default(uuid())
   name     String @unique // "Solo", "Small", "Medium", "Large", "Enterprise"
@@ -81,11 +123,13 @@ model Membership {
   organizationId String
 
   isOwner Boolean @default(false)
+  isActive Boolean @default(true)
 
   user         User         @relation(fields: [userId], references: [id])
   organization Organization @relation(fields: [organizationId], references: [id])
 
   permissions MembershipPermission[]
+  invitations StaffInvitation[]
 
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
@@ -94,6 +138,26 @@ model Membership {
   @@map("memberships")
 }
 
+model StaffInvitation {
+  id String @id @default(uuid())
+
+  membershipId String
+  invitedById  String
+  tokenHash    String   @unique
+  expiresAt    DateTime
+  acceptedAt   DateTime?
+  revokedAt    DateTime?
+
+  membership Membership @relation(fields: [membershipId], references: [id], onDelete: Cascade)
+  invitedBy  User       @relation(fields: [invitedById], references: [id], onDelete: Cascade)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([membershipId, createdAt])
+  @@map("staff_invitations")
+}
+
 model Permission {
   id          String  @id @default(uuid())
   name        String  @unique

backend/prisma/seed.ts

@@ -1,6 +1,5 @@
 // backend/prisma/seed.ts
 import { PrismaClient } from '@prisma/client';
-import * as bcrypt from 'bcrypt';
 import { config } from 'dotenv';
 import path from 'path';
 
@@ -29,14 +28,14 @@ async function main() {
   console.log('✅ Database connected successfully');
 
   // Create organization types
-  const clinicType = await prisma.organizationType.upsert({
+  await prisma.organizationType.upsert({
     where: { name: 'CLINIC' },
     update: {},
     create: { name: 'CLINIC' },
   });
   console.log('✅ Created clinic type');
 
-  const labType = await prisma.organizationType.upsert({
+  await prisma.organizationType.upsert({
     where: { name: 'LAB' },
     update: {},
     create: { name: 'LAB' },
@@ -46,10 +45,10 @@ async function main() {
   // Create plans
   const plans = [
     { name: 'trial', maxUsers: 5, price: 0, features: {} },
-    { name: 'Small', maxUsers: 5, price: 79, features: {} },
-    { name: 'Medium', maxUsers: 10, price: 129, features: {} },
-    { name: 'Large', maxUsers: 15, price: 179, features: {} },
-    { name: 'Enterprise', maxUsers: 999999, price: 299, features: {} },
+    { name: 'Small', maxUsers: 5, price: 150, features: {} },
+    { name: 'Medium', maxUsers: 10, price: 250, features: {} },
+    { name: 'Large', maxUsers: 15, price: 400, features: {} },
+    { name: 'Enterprise', maxUsers: 999999, price: 1000, features: {} },
   ];
 
   for (const plan of plans) {
@@ -61,32 +60,43 @@ async function main() {
   }
   console.log('✅ Created plans');
 
-  // Create features and permissions
+  // Minimal permission model (confirmed):
+  // - Sidebar tabs use READ/EDIT
+  // - EDIT implies READ in app logic
+  // - Owners effectively get all permissions
   const features = [
     {
-      name: 'Patient Management',
-      permissions: ['VIEW_PATIENTS', 'CREATE_PATIENTS', 'EDIT_PATIENTS', 'DELETE_PATIENTS']
+      name: 'Today',
+      permissions: ['TAB_TODAY_READ', 'TAB_TODAY_EDIT'],
     },
     {
-      name: 'Order Management',
-      permissions: ['VIEW_ORDERS', 'CREATE_ORDERS', 'EDIT_ORDERS', 'DELETE_ORDERS', 'TRACK_ORDERS']
+      name: 'Staff',
+      permissions: ['TAB_STAFF_READ', 'TAB_STAFF_EDIT'],
     },
     {
-      name: 'Case Management',
-      permissions: ['VIEW_CASES', 'CREATE_CASES', 'EDIT_CASES', 'DELETE_CASES']
+      name: 'Labs / Clinics',
+      permissions: ['TAB_LAB_READ', 'TAB_LAB_EDIT'],
     },
     {
-      name: 'Reports',
-      permissions: ['VIEW_REPORTS', 'EXPORT_REPORTS']
+      name: 'Patients',
+      permissions: ['TAB_PATIENTS_READ', 'TAB_PATIENTS_EDIT'],
     },
     {
-      name: 'Team Management',
-      permissions: ['INVITE_USERS', 'REMOVE_USERS', 'MANAGE_PERMISSIONS']
+      name: 'Appointment',
+      permissions: ['TAB_APPOINTMENTS_READ', 'TAB_APPOINTMENTS_EDIT'],
+    },
+    {
+      name: 'Treatment',
+      permissions: ['TAB_TREATMENT_READ', 'TAB_TREATMENT_EDIT'],
     },
     {
       name: 'Billing',
-      permissions: ['VIEW_INVOICES', 'CREATE_INVOICES', 'MANAGE_PAYMENTS']
-    }
+      permissions: ['TAB_BILLING_READ', 'TAB_BILLING_EDIT'],
+    },
+    {
+      name: 'Reports',
+      permissions: ['TAB_REPORTS_READ', 'TAB_REPORTS_EDIT'],
+    },
   ];
 
   for (const feature of features) {
@@ -109,7 +119,7 @@ async function main() {
   }
   console.log('✅ Created features and permissions');
 
-  console.log('🌱 Seeding completed successfully!'); ``
+  console.log('🌱 Seeding completed successfully!');
 }
 
 main()

backend/src/app.controller.ts

@@ -22,4 +22,13 @@ export class AppController {
   getHello(): string {
     return this.appService.getHello();
   }
+
+  /** Used by Docker / load balancer health checks (GET /api/health) */
+  @Get('health')
+  health() {
+    return {
+      status: 'ok',
+      timestamp: new Date().toISOString(),
+    };
+  }
 }

backend/src/app.module.ts

@@ -6,6 +6,8 @@ import { AppController } from './app.controller';
 import { AppService } from './app.service';
 import { AdminModule } from './admin/admin.module';
 import { PrismaModule } from '../prisma/prisma.module'; // ✅
+import { PatientsModule } from './modules/patients/patients.module';
+import { StaffModule } from './modules/staff/staff.module';
 
 @Module({
   imports: [
@@ -15,6 +17,8 @@ import { PrismaModule } from '../prisma/prisma.module'; // ✅
     }),
     PrismaModule, // ✅ ADD THIS
     AuthModule,
+    PatientsModule,
+    StaffModule,
     AdminModule.forRoot(),
   ],
   controllers: [AppController],

backend/src/common/permissions.spec.ts

@@ -0,0 +1,37 @@
+import { isUnlimitedSeats, normalizeTabPermissions, SEAT_UNLIMITED_THRESHOLD } from './permissions';
+
+describe('normalizeTabPermissions', () => {
+  it('adds READ when EDIT is present', () => {
+    expect(normalizeTabPermissions(['TAB_PATIENTS_EDIT'])).toEqual([
+      'TAB_PATIENTS_READ',
+      'TAB_PATIENTS_EDIT',
+    ]);
+  });
+
+  it('dedupes and sorts', () => {
+    expect(
+      normalizeTabPermissions([
+        'TAB_TODAY_READ',
+        'TAB_TODAY_EDIT',
+        'TAB_TODAY_READ',
+        'bogus',
+      ]),
+    ).toEqual(['TAB_TODAY_READ', 'TAB_TODAY_EDIT']);
+  });
+
+  it('accepts empty array', () => {
+    expect(normalizeTabPermissions([])).toEqual([]);
+  });
+});
+
+describe('isUnlimitedSeats', () => {
+  it('treats sentinel as unlimited', () => {
+    expect(isUnlimitedSeats(SEAT_UNLIMITED_THRESHOLD)).toBe(true);
+    expect(isUnlimitedSeats(SEAT_UNLIMITED_THRESHOLD + 1)).toBe(true);
+  });
+
+  it('treats normal caps as limited', () => {
+    expect(isUnlimitedSeats(5)).toBe(false);
+    expect(isUnlimitedSeats(15)).toBe(false);
+  });
+});

backend/src/common/permissions.ts

@@ -0,0 +1,60 @@
+/** Tab permissions — keep in sync with prisma seed and AuthService ALL_PERMISSIONS */
+export const ALL_TAB_PERMISSIONS = [
+  'TAB_TODAY_READ',
+  'TAB_TODAY_EDIT',
+  'TAB_STAFF_READ',
+  'TAB_STAFF_EDIT',
+  'TAB_LAB_READ',
+  'TAB_LAB_EDIT',
+  'TAB_PATIENTS_READ',
+  'TAB_PATIENTS_EDIT',
+  'TAB_APPOINTMENTS_READ',
+  'TAB_APPOINTMENTS_EDIT',
+  'TAB_TREATMENT_READ',
+  'TAB_TREATMENT_EDIT',
+  'TAB_BILLING_READ',
+  'TAB_BILLING_EDIT',
+  'TAB_REPORTS_READ',
+  'TAB_REPORTS_EDIT',
+] as const;
+
+export type TabPermission = (typeof ALL_TAB_PERMISSIONS)[number];
+
+const ALL_TAB_SET = new Set<string>(ALL_TAB_PERMISSIONS);
+const TAB_ORDER_INDEX = new Map<string, number>(
+  ALL_TAB_PERMISSIONS.map((p, i) => [p, i]),
+);
+
+/** Enterprise / unlimited seat plans use this sentinel in seed data */
+export const SEAT_UNLIMITED_THRESHOLD = 999999;
+
+export function isUnlimitedSeats(maxUsers: number): boolean {
+  return maxUsers >= SEAT_UNLIMITED_THRESHOLD;
+}
+
+/** EDIT implies READ for the same feature tab */
+const EDIT_TO_READ: Record<string, string> = {
+  TAB_TODAY_EDIT: 'TAB_TODAY_READ',
+  TAB_PATIENTS_EDIT: 'TAB_PATIENTS_READ',
+  TAB_APPOINTMENTS_EDIT: 'TAB_APPOINTMENTS_READ',
+  TAB_STAFF_EDIT: 'TAB_STAFF_READ',
+  TAB_LAB_EDIT: 'TAB_LAB_READ',
+  TAB_TREATMENT_EDIT: 'TAB_TREATMENT_READ',
+  TAB_BILLING_EDIT: 'TAB_BILLING_READ',
+  TAB_REPORTS_EDIT: 'TAB_REPORTS_READ',
+};
+
+/**
+ * Dedupe, drop unknown strings, and add implied READ permissions for each EDIT.
+ */
+export function normalizeTabPermissions(names: string[]): string[] {
+  const out = new Set<string>();
+  for (const raw of names) {
+    const n = typeof raw === 'string' ? raw.trim() : '';
+    if (!n || !ALL_TAB_SET.has(n)) continue;
+    out.add(n);
+    const read = EDIT_TO_READ[n];
+    if (read) out.add(read);
+  }
+  return [...out].sort((a, b) => (TAB_ORDER_INDEX.get(a) ?? 0) - (TAB_ORDER_INDEX.get(b) ?? 0));
+}

backend/src/modules/auth/auth.controller.ts

@@ -25,6 +25,7 @@ import {
 import { AuthService } from './auth.service';
 import { LoginDto } from './dto/login.dto';
 import { RegisterDto } from './dto/register.dto';
+import { CreateOrganizationDto } from './dto/create-organization.dto';
 import { JwtAuthGuard } from './guards/jwt-auth.guard';
 import { LocalAuthGuard } from './guards/local-auth.guard';
 
@@ -120,6 +121,14 @@ export class AuthController {
     };
   }
 
+  @Post('organizations')
+  @UseGuards(JwtAuthGuard)
+  @ApiBearerAuth('JWT-auth')
+  @ApiOperation({ summary: 'Create organization for current user' })
+  async createOrganization(@Req() req, @Body() dto: CreateOrganizationDto) {
+    return this.authService.createOrganization(req.user.id, dto);
+  }
+
   // =========================
   // PROFILE
   // =========================
@@ -136,6 +145,42 @@ export class AuthController {
     return this.authService.getProfile(req.user.id);
   }
 
+  @Get('subscription-alert')
+  @UseGuards(JwtAuthGuard)
+  @ApiBearerAuth('JWT-auth')
+  @ApiOperation({
+    summary:
+      'Owner-only: seat / trial status for warning indicator (current org from JWT)',
+  })
+  async getSubscriptionAlert(@Req() req) {
+    return this.authService.getOwnerSubscriptionAlert(
+      req.user.id,
+      req.user.organizationId,
+    );
+  }
+
+  // =========================
+  // LOGOUT
+  // =========================
+  @Post('logout')
+  @HttpCode(HttpStatus.OK)
+  @ApiOperation({ summary: 'Logout current user' })
+  @ApiResponse({ status: 200, description: 'Logout successful' })
+  async logout(@Req() req, @Res({ passthrough: true }) res: Response) {
+    const accessToken = req?.cookies?.accessToken;
+
+    if (accessToken) {
+      await this.authService.logout(accessToken);
+    }
+
+    this.clearAuthCookies(res);
+
+    return {
+      success: true,
+      message: 'Logged out successfully',
+    };
+  }
+
   // =========================
   // TEST
   // =========================
@@ -174,4 +219,19 @@ export class AuthController {
       path: '/',
     });
   }
+
+  private clearAuthCookies(res: Response) {
+    res.clearCookie('accessToken', {
+      httpOnly: true,
+      secure: false,
+      sameSite: 'lax',
+      path: '/',
+    });
+    res.clearCookie('refreshToken', {
+      httpOnly: true,
+      secure: false,
+      sameSite: 'lax',
+      path: '/',
+    });
+  }
 }

backend/src/modules/auth/auth.service.ts

@@ -12,30 +12,37 @@ import * as bcrypt from 'bcrypt';
 import { PrismaService } from '../../../prisma/prisma.service';
 import { LoginDto } from './dto/login.dto';
 import { RegisterDto } from './dto/register.dto';
+import { CreateOrganizationDto } from './dto/create-organization.dto';
 import { JwtPayload } from './interfaces/jwt-payload.interface';
 
 const ALL_PERMISSIONS = [
-  'VIEW_PATIENTS',
-  'CREATE_PATIENTS',
-  'EDIT_PATIENTS',
-  'DELETE_PATIENTS',
-  'VIEW_ORDERS',
-  'CREATE_ORDERS',
-  'EDIT_ORDERS',
-  'DELETE_ORDERS',
-  'TRACK_ORDERS',
-  'VIEW_CASES',
-  'CREATE_CASES',
-  'EDIT_CASES',
-  'DELETE_CASES',
-  'VIEW_REPORTS',
-  'EXPORT_REPORTS',
-  'INVITE_USERS',
-  'REMOVE_USERS',
-  'MANAGE_PERMISSIONS',
-  'VIEW_INVOICES',
-  'CREATE_INVOICES',
-  'MANAGE_PAYMENTS',
+  'TAB_TODAY_READ',
+  'TAB_TODAY_EDIT',
+  'TAB_STAFF_READ',
+  'TAB_STAFF_EDIT',
+  'TAB_LAB_READ',
+  'TAB_LAB_EDIT',
+  'TAB_PATIENTS_READ',
+  'TAB_PATIENTS_EDIT',
+  'TAB_APPOINTMENTS_READ',
+  'TAB_APPOINTMENTS_EDIT',
+  'TAB_TREATMENT_READ',
+  'TAB_TREATMENT_EDIT',
+  'TAB_BILLING_READ',
+  'TAB_BILLING_EDIT',
+  'TAB_REPORTS_READ',
+  'TAB_REPORTS_EDIT',
+];
+
+const READ_ONLY_PERMISSIONS = [
+  'TAB_TODAY_READ',
+  'TAB_STAFF_READ',
+  'TAB_LAB_READ',
+  'TAB_PATIENTS_READ',
+  'TAB_APPOINTMENTS_READ',
+  'TAB_TREATMENT_READ',
+  'TAB_BILLING_READ',
+  'TAB_REPORTS_READ',
 ];
 
 @Injectable()
@@ -54,14 +61,16 @@ export class AuthService {
    */
   async validateUser(email: string, password: string): Promise<any> {
     try {
+      const normalizedEmail = email.trim().toLowerCase();
       const user = await this.prisma.user.findUnique({
-        where: { email },
+        where: { email: normalizedEmail },
         include: {
           memberships: {
             include: {
               organization: {
                 include: {
                   type: true, // Include organization type (CLINIC/LAB)
+                  plan: true,
                 }
               },
               permissions: {
@@ -140,15 +149,20 @@ export class AuthService {
       });
 
       // Transform memberships to include organization info and permissions
-      const organizations = user.memberships?.map(membership => ({
+      const organizations = this.toActiveOrganizations(user.memberships).map(membership => ({
         id: membership.organization.id,
         name: membership.organization.name,
         type: membership.organization.type.name, // 'CLINIC' or 'LAB'
         isOwner: membership.isOwner,
-        permissions: membership.isOwner
-          ? ALL_PERMISSIONS
-          : membership.permissions?.map(p => p.permission.name) || [],
-      })) || [];
+        permissions: this.getMembershipPermissions(membership),
+        plan: membership.organization.plan
+          ? {
+              name: membership.organization.plan.name,
+              maxUsers: membership.organization.plan.maxUsers,
+              price: membership.organization.plan.price,
+            }
+          : undefined,
+      }));
 
       return {
         success: true,
@@ -176,7 +190,8 @@ export class AuthService {
    * @returns Created user info without password
    */
   async register(registerDto: RegisterDto) {
-    const { email, password, name, organizationName, organizationType } = registerDto;
+    const { password, name, organizationName, organizationEmail, organizationType } = registerDto;
+    const email = registerDto.email.trim().toLowerCase();
 
     // 1. Check existing user
     const existingUser = await this.prisma.user.findUnique({
@@ -184,7 +199,7 @@ export class AuthService {
     });
 
     if (existingUser) {
-      throw new ConflictException('User already exists');
+      throw new ConflictException('User already exists. Please login and create a new organization from your account.');
     }
 
     // 2. Hash password
@@ -198,16 +213,15 @@ export class AuthService {
           email,
           passwordHash: hashedPassword,
           name,
+          trialUsedAt: new Date(),
         },
       });
 
       // Create organization
       const organization = await tx.organization.create({
         data: {
-          name: registerDto.organizationName,
-
-          // REQUIRED FIELDS 👇
-          email: registerDto.email, // or separate org email if you have one
+          name: organizationName,
+          email: organizationEmail,
 
           owner: {
             connect: { id: user.id },
@@ -219,7 +233,7 @@ export class AuthService {
 
           type: {
             connect: {
-              name: registerDto.organizationType, // 'CLINIC' | 'LAB'
+              name: organizationType, // 'CLINIC' | 'LAB'
             },
           },
         },
@@ -247,6 +261,52 @@ export class AuthService {
     return this.login({ email, password } as any, validatedUser);
   }
 
+  async createOrganization(userId: string, dto: CreateOrganizationDto) {
+    const owner = await this.prisma.user.findUnique({
+      where: { id: userId },
+      select: { id: true },
+    });
+
+    if (!owner) {
+      throw new UnauthorizedException('User not found');
+    }
+
+    const organization = await this.prisma.$transaction(async (tx) => {
+      const createdOrganization = await tx.organization.create({
+        data: {
+          name: dto.organizationName,
+          email: dto.organizationEmail,
+          owner: {
+            connect: { id: userId },
+          },
+          type: {
+            connect: { name: dto.organizationType },
+          },
+        },
+      });
+
+      await tx.membership.create({
+        data: {
+          userId,
+          organizationId: createdOrganization.id,
+          isOwner: true,
+        },
+      });
+      return createdOrganization;
+    });
+
+    return {
+      success: true,
+      data: {
+        organization: {
+          id: organization.id,
+          name: organization.name,
+          email: organization.email,
+        },
+      },
+    };
+  }
+
   /**
    * Get user profile with all memberships and permissions
    * @param userId - User ID from JWT token
@@ -262,6 +322,7 @@ export class AuthService {
               organization: {
                 include: {
                   type: true,
+                  plan: true,
                 },
               },
               permissions: {
@@ -281,13 +342,20 @@ export class AuthService {
       const { passwordHash, ...result } = user;
 
       // Transform memberships for frontend consumption
-      const organizations = user.memberships?.map(membership => ({
+      const organizations = this.toActiveOrganizations(user.memberships).map(membership => ({
         id: membership.organization.id,
         name: membership.organization.name,
         type: membership.organization.type.name,
         isOwner: membership.isOwner,
-        permissions: membership.permissions?.map(p => p.permission.name) || [],
-      })) || [];
+        permissions: this.getMembershipPermissions(membership),
+        plan: membership.organization.plan
+          ? {
+              name: membership.organization.plan.name,
+              maxUsers: membership.organization.plan.maxUsers,
+              price: membership.organization.plan.price,
+            }
+          : undefined,
+      }));
 
       return {
         success: true,
@@ -352,6 +420,7 @@ export class AuthService {
                   organization: {
                     include: {
                       type: true,
+                      plan: true,
                     },
                   },
                   permissions: {
@@ -392,13 +461,20 @@ export class AuthService {
       });
 
       // Transform memberships for response
-      const organizations = session.user.memberships?.map(membership => ({
+      const organizations = this.toActiveOrganizations(session.user.memberships).map(membership => ({
         id: membership.organization.id,
         name: membership.organization.name,
         type: membership.organization.type.name,
         isOwner: membership.isOwner,
-        permissions: membership.permissions?.map(p => p.permission.name) || [],
-      })) || [];
+        permissions: this.getMembershipPermissions(membership),
+        plan: membership.organization.plan
+          ? {
+              name: membership.organization.plan.name,
+              maxUsers: membership.organization.plan.maxUsers,
+              price: membership.organization.plan.price,
+            }
+          : undefined,
+      }));
 
       return {
         success: true,
@@ -569,6 +645,7 @@ export class AuthService {
                   organization: {
                     include: {
                       type: true,
+                      plan: true,
                     },
                   },
                   permissions: {
@@ -589,13 +666,20 @@ export class AuthService {
 
       const { passwordHash, ...user } = session.user;
 
-      const organizations = session.user.memberships?.map(membership => ({
+      const organizations = this.toActiveOrganizations(session.user.memberships).map(membership => ({
         id: membership.organization.id,
         name: membership.organization.name,
         type: membership.organization.type.name,
         isOwner: membership.isOwner,
-        permissions: membership.permissions?.map(p => p.permission.name) || [],
-      })) || [];
+        permissions: this.getMembershipPermissions(membership),
+        plan: membership.organization.plan
+          ? {
+              name: membership.organization.plan.name,
+              maxUsers: membership.organization.plan.maxUsers,
+              price: membership.organization.plan.price,
+            }
+          : undefined,
+      }));
 
       return {
         success: true,
@@ -617,6 +701,7 @@ export class AuthService {
         organizationId,
       },
       include: {
+        user: true,
         organization: {
           include: {
             type: true,
@@ -634,11 +719,14 @@ export class AuthService {
     if (!membership) {
       throw new UnauthorizedException('Access denied to this organization');
     }
+    if (!membership.isOwner && !membership.isActive) {
+      throw new UnauthorizedException('Your invitation is still pending activation');
+    }
 
     // 2. Build payload WITH org context
     const payload = {
       sub: userId,
-      email: membership.organization.email,
+      email: membership.user.email,
       organizationId: membership.organizationId,
       type: 'access',
     };
@@ -650,7 +738,7 @@ export class AuthService {
     });
 
     // 4. Format permissions
-    const permissions = membership.permissions.map(p => p.permission.name);
+    const permissions = this.getMembershipPermissions(membership);
 
     return {
       success: true,
@@ -660,8 +748,153 @@ export class AuthService {
           id: membership.organization.id,
           name: membership.organization.name,
           type: membership.organization.type.name,
+          isOwner: membership.isOwner,
+          permissions,
+          plan: membership.organization.plan
+            ? {
+                name: membership.organization.plan.name,
+                maxUsers: membership.organization.plan.maxUsers,
+                price: membership.organization.plan.price,
+              }
+            : undefined,
         },
-        permissions,
+      },
+    };
+  }
+
+  private toActiveOrganizations(
+    memberships: Array<{
+      isOwner: boolean;
+      isActive: boolean;
+      organization: {
+        id: string;
+        name: string;
+        type: { name: string };
+        plan?: { name: string; maxUsers: number; price: number } | null;
+      };
+      permissions?: Array<{ permission: { name: string } }>;
+    }> = [],
+  ) {
+    return memberships.filter((m) => m.isOwner || m.isActive);
+  }
+
+  private getMembershipPermissions(membership: {
+    isOwner: boolean;
+    organization: {
+      plan?: { name: string; maxUsers: number; price: number } | null;
+    };
+    permissions?: Array<{ permission: { name: string } }>;
+  }): string[] {
+    if (membership.isOwner) {
+      return membership.organization.plan ? ALL_PERMISSIONS : READ_ONLY_PERMISSIONS;
+    }
+    return membership.permissions?.map((p) => p.permission.name) || [];
+  }
+
+  /**
+   * Owner-only subscription / seat alerts for the current org (from JWT).
+   * Used for a subtle warning indicator in the app shell (not staff-facing banners).
+   */
+  async getOwnerSubscriptionAlert(userId: string, organizationId: string | undefined) {
+    if (!organizationId) {
+      return {
+        success: true,
+        data: {
+          showWarning: false,
+          noActiveSubscription: false,
+          seatsLow: false,
+          trialEndingSoon: false,
+          trialExpired: false,
+          daysUntilPlanEnd: null,
+          planEndsAt: null,
+        },
+      };
+    }
+
+    const membership = await this.prisma.membership.findFirst({
+      where: { userId, organizationId },
+      include: {
+        organization: {
+          include: { plan: true },
+        },
+      },
+    });
+
+    if (!membership || !membership.isOwner) {
+      return {
+        success: true,
+        data: {
+          showWarning: false,
+          noActiveSubscription: false,
+          seatsLow: false,
+          trialEndingSoon: false,
+          trialExpired: false,
+          daysUntilPlanEnd: null,
+          planEndsAt: null,
+        },
+      };
+    }
+
+    const org = membership.organization;
+    const plan = org.plan;
+    if (!plan) {
+      return {
+        success: true,
+        data: {
+          showWarning: true,
+          noActiveSubscription: true,
+          seatsLow: false,
+          trialEndingSoon: false,
+          trialExpired: false,
+          seatsUsed: 0,
+          seatsLimit: null,
+          daysUntilTrialEnd: null,
+          trialEndsAt: null,
+          daysUntilPlanEnd: null,
+          planEndsAt: null,
+        },
+      };
+    }
+    const maxUsers = plan.maxUsers;
+    const seatsUsed = await this.prisma.membership.count({
+      where: {
+        organizationId: org.id,
+        OR: [{ isOwner: true }, { isActive: true }],
+      },
+    });
+
+    const unlimited = maxUsers >= 999999;
+    const remaining = unlimited ? Infinity : maxUsers - seatsUsed;
+    const seatsLow =
+      !unlimited && remaining >= 0 && remaining <= 2 && maxUsers > 0;
+
+    // Current pricing model: trial lasts 30 days; paid plans last 90 days.
+    const durationDays = plan.name === 'trial' ? 30 : 90;
+    const end = new Date(org.createdAt);
+    end.setDate(end.getDate() + durationDays);
+    const planEndsAt = end.toISOString();
+    const ms = end.getTime() - Date.now();
+    const daysUntilPlanEnd = Math.ceil(ms / (1000 * 60 * 60 * 24));
+
+    const trialExpired = plan.name === 'trial' && daysUntilPlanEnd <= 0;
+    const trialEndingSoon = plan.name === 'trial' && daysUntilPlanEnd > 0 && daysUntilPlanEnd <= 7;
+
+    const showWarning = seatsLow || trialEndingSoon || trialExpired;
+
+    return {
+      success: true,
+      data: {
+        showWarning,
+        noActiveSubscription: false,
+        seatsLow,
+        trialEndingSoon,
+        trialExpired,
+        seatsUsed,
+        seatsLimit: maxUsers,
+        daysUntilTrialEnd: plan.name === 'trial' ? daysUntilPlanEnd : null,
+        trialEndsAt: plan.name === 'trial' ? planEndsAt : null,
+        daysUntilPlanEnd,
+        planEndsAt,
       },
     };
   }

backend/src/modules/auth/dto/create-organization.dto.ts

@@ -0,0 +1,16 @@
+import { IsEmail, IsEnum, IsOptional, IsString } from 'class-validator';
+
+export class CreateOrganizationDto {
+  @IsString()
+  organizationName: string;
+
+  @IsEmail()
+  organizationEmail: string;
+
+  @IsEnum(['CLINIC', 'LAB'])
+  organizationType: 'CLINIC' | 'LAB';
+
+  @IsOptional()
+  @IsString()
+  planName?: string;
+}

backend/src/modules/auth/dto/register.dto.ts

@@ -14,6 +14,9 @@ export class RegisterDto {
   @IsString()
   organizationName: string;
 
+  @IsEmail()
+  organizationEmail: string;
+
   @IsEnum(['CLINIC', 'LAB'])
   organizationType: 'CLINIC' | 'LAB';
 }

backend/src/modules/auth/interfaces/jwt-payload.interface.ts

@@ -2,6 +2,7 @@
 export interface JwtPayload {
   sub: string; // user id
   email: string;
+  organizationId?: string;
   type?: 'access' | 'refresh';
 }
 

backend/src/modules/auth/strategies/jwt.strategy.ts

@@ -31,6 +31,9 @@ export class JwtStrategy extends PassportStrategy(Strategy) {
     }
 
     const { passwordHash, ...result } = user;
-    return result;
+    return {
+      ...result,
+      organizationId: payload.organizationId,
+    };
   }
 }

backend/src/modules/patients/dto/create-patient.dto.ts

@@ -0,0 +1,29 @@
+import { IsDateString, IsEmail, IsOptional, IsString, MaxLength } from 'class-validator';
+
+export class CreatePatientDto {
+  @IsString()
+  @MaxLength(80)
+  firstName: string;
+
+  @IsString()
+  @MaxLength(80)
+  lastName: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(30)
+  phone?: string;
+
+  @IsOptional()
+  @IsEmail()
+  email?: string;
+
+  @IsOptional()
+  @IsDateString()
+  dateOfBirth?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(1000)
+  notes?: string;
+}

backend/src/modules/patients/dto/create-treatment-history.dto.ts

@@ -0,0 +1,28 @@
+import { IsDateString, IsNumber, IsOptional, IsString, MaxLength } from 'class-validator';
+
+export class CreateTreatmentHistoryDto {
+  @IsString()
+  @MaxLength(120)
+  title: string;
+
+  @IsString()
+  @MaxLength(40)
+  status: string;
+
+  @IsDateString()
+  treatmentAt: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(20)
+  tooth?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(1000)
+  notes?: string;
+
+  @IsOptional()
+  @IsNumber()
+  totalCost?: number;
+}

backend/src/modules/patients/dto/list-patients.dto.ts

@@ -0,0 +1,21 @@
+import { Transform } from 'class-transformer';
+import { IsInt, IsOptional, IsString, Max, Min } from 'class-validator';
+
+export class ListPatientsDto {
+  @IsOptional()
+  @IsString()
+  q?: string;
+
+  @IsOptional()
+  @Transform(({ value }) => Number(value))
+  @IsInt()
+  @Min(1)
+  page = 1;
+
+  @IsOptional()
+  @Transform(({ value }) => Number(value))
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit = 10;
+}

backend/src/modules/patients/dto/update-patient.dto.ts

@@ -0,0 +1,4 @@
+import { PartialType } from '@nestjs/swagger';
+import { CreatePatientDto } from './create-patient.dto';
+
+export class UpdatePatientDto extends PartialType(CreatePatientDto) {}

backend/src/modules/patients/patients.controller.ts

@@ -0,0 +1,77 @@
+import {
+  Body,
+  Controller,
+  Get,
+  Param,
+  ParseIntPipe,
+  Patch,
+  Post,
+  Query,
+  Req,
+  UseGuards,
+} from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { CreatePatientDto } from './dto/create-patient.dto';
+import { ListPatientsDto } from './dto/list-patients.dto';
+import { UpdatePatientDto } from './dto/update-patient.dto';
+import { PatientsService } from './patients.service';
+import { CreateTreatmentHistoryDto } from './dto/create-treatment-history.dto';
+
+@ApiTags('patients')
+@ApiBearerAuth('JWT-auth')
+@UseGuards(JwtAuthGuard)
+@Controller('patients')
+export class PatientsController {
+  constructor(private readonly patientsService: PatientsService) {}
+
+  @Post()
+  @ApiOperation({ summary: 'Create a patient for current organization' })
+  create(@Body() createPatientDto: CreatePatientDto, @Req() req) {
+    const organizationId = this.patientsService.getOrganizationIdFromUser(req.user);
+    return this.patientsService.create(createPatientDto, organizationId);
+  }
+
+  @Get()
+  @ApiOperation({ summary: 'List patients with search and pagination' })
+  findAll(@Query() query: ListPatientsDto, @Req() req) {
+    const organizationId = this.patientsService.getOrganizationIdFromUser(req.user);
+    return this.patientsService.findAll(query, organizationId);
+  }
+
+  @Get(':id')
+  @ApiOperation({ summary: 'Get one patient by id' })
+  findOne(@Param('id') id: string, @Req() req) {
+    const organizationId = this.patientsService.getOrganizationIdFromUser(req.user);
+    return this.patientsService.findOne(id, organizationId);
+  }
+
+  @Patch(':id')
+  @ApiOperation({ summary: 'Update patient' })
+  update(@Param('id') id: string, @Body() updatePatientDto: UpdatePatientDto, @Req() req) {
+    const organizationId = this.patientsService.getOrganizationIdFromUser(req.user);
+    return this.patientsService.update(id, updatePatientDto, organizationId);
+  }
+
+  @Get(':id/treatments')
+  @ApiOperation({ summary: 'Get patient treatment history' })
+  findTreatments(
+    @Param('id') id: string,
+    @Query('limit', new ParseIntPipe({ optional: true })) limit = 20,
+    @Req() req,
+  ) {
+    const organizationId = this.patientsService.getOrganizationIdFromUser(req.user);
+    return this.patientsService.findTreatments(id, organizationId, limit);
+  }
+
+  @Post(':id/treatments')
+  @ApiOperation({ summary: 'Add treatment history item for a patient' })
+  addTreatment(
+    @Param('id') id: string,
+    @Body() dto: CreateTreatmentHistoryDto,
+    @Req() req,
+  ) {
+    const organizationId = this.patientsService.getOrganizationIdFromUser(req.user);
+    return this.patientsService.addTreatment(id, dto, organizationId);
+  }
+}

backend/src/modules/patients/patients.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { PrismaService } from '../../../prisma/prisma.service';
+import { PatientsController } from './patients.controller';
+import { PatientsService } from './patients.service';
+
+@Module({
+  controllers: [PatientsController],
+  providers: [PatientsService, PrismaService],
+})
+export class PatientsModule {}

backend/src/modules/patients/patients.service.ts

@@ -0,0 +1,139 @@
+import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
+import { PrismaService } from '../../../prisma/prisma.service';
+import { CreatePatientDto } from './dto/create-patient.dto';
+import { ListPatientsDto } from './dto/list-patients.dto';
+import { UpdatePatientDto } from './dto/update-patient.dto';
+import { CreateTreatmentHistoryDto } from './dto/create-treatment-history.dto';
+
+@Injectable()
+export class PatientsService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async create(createPatientDto: CreatePatientDto, organizationId: string) {
+    const patient = await this.prisma.patient.create({
+      data: {
+        ...createPatientDto,
+        dateOfBirth: createPatientDto.dateOfBirth ? new Date(createPatientDto.dateOfBirth) : null,
+        organizationId,
+      },
+    });
+
+    return { success: true, data: patient };
+  }
+
+  async findAll(query: ListPatientsDto, organizationId: string) {
+    const { page = 1, limit = 10, q } = query;
+    const skip = (page - 1) * limit;
+
+    const where = {
+      organizationId,
+      ...(q
+        ? {
+            OR: [
+              { firstName: { contains: q, mode: 'insensitive' as const } },
+              { lastName: { contains: q, mode: 'insensitive' as const } },
+              { email: { contains: q, mode: 'insensitive' as const } },
+              { phone: { contains: q, mode: 'insensitive' as const } },
+            ],
+          }
+        : {}),
+    };
+
+    const [items, total] = await Promise.all([
+      this.prisma.patient.findMany({
+        where,
+        skip,
+        take: limit,
+        orderBy: [{ updatedAt: 'desc' }],
+      }),
+      this.prisma.patient.count({ where }),
+    ]);
+
+    return {
+      success: true,
+      data: {
+        items,
+        pagination: {
+          page,
+          limit,
+          total,
+          totalPages: Math.max(1, Math.ceil(total / limit)),
+        },
+      },
+    };
+  }
+
+  async findOne(id: string, organizationId: string) {
+    const patient = await this.prisma.patient.findFirst({
+      where: { id, organizationId },
+    });
+
+    if (!patient) {
+      throw new NotFoundException('Patient not found');
+    }
+
+    return { success: true, data: patient };
+  }
+
+  async update(id: string, updatePatientDto: UpdatePatientDto, organizationId: string) {
+    await this.ensurePatient(id, organizationId);
+
+    const patient = await this.prisma.patient.update({
+      where: { id },
+      data: {
+        ...updatePatientDto,
+        dateOfBirth: updatePatientDto.dateOfBirth ? new Date(updatePatientDto.dateOfBirth) : undefined,
+      },
+    });
+
+    return { success: true, data: patient };
+  }
+
+  async findTreatments(patientId: string, organizationId: string, limit = 20) {
+    await this.ensurePatient(patientId, organizationId);
+
+    const items = await this.prisma.patientTreatmentHistory.findMany({
+      where: { patientId },
+      orderBy: [{ treatmentAt: 'desc' }],
+      take: limit,
+    });
+
+    return { success: true, data: items };
+  }
+
+  async addTreatment(
+    patientId: string,
+    dto: CreateTreatmentHistoryDto,
+    organizationId: string,
+  ) {
+    await this.ensurePatient(patientId, organizationId);
+
+    const treatment = await this.prisma.patientTreatmentHistory.create({
+      data: {
+        ...dto,
+        treatmentAt: new Date(dto.treatmentAt),
+        patientId,
+      },
+    });
+
+    return { success: true, data: treatment };
+  }
+
+  private async ensurePatient(id: string, organizationId: string) {
+    const patient = await this.prisma.patient.findFirst({
+      where: { id, organizationId },
+      select: { id: true },
+    });
+
+    if (!patient) {
+      throw new NotFoundException('Patient not found');
+    }
+  }
+
+  getOrganizationIdFromUser(user: { organizationId?: string }) {
+    if (!user?.organizationId) {
+      throw new BadRequestException('Organization is not selected');
+    }
+    return user.organizationId;
+  }
+}

backend/src/modules/staff/dto/accept-staff-invite.dto.ts

@@ -0,0 +1,14 @@
+import { IsString, MinLength } from 'class-validator';
+
+export class AcceptStaffInviteDto {
+  @IsString()
+  token: string;
+
+  @IsString()
+  @MinLength(8)
+  password: string;
+
+  @IsString()
+  @MinLength(1)
+  name: string;
+}

backend/src/modules/staff/dto/invite-staff.dto.ts

@@ -0,0 +1,15 @@
+import { IsArray, IsEmail, IsString, MinLength } from 'class-validator';
+
+export class InviteStaffDto {
+  @IsEmail()
+  email: string;
+
+  @IsString()
+  @MinLength(1)
+  name: string;
+
+  /** TAB_* permission names; EDIT implies READ after normalization. */
+  @IsArray()
+  @IsString({ each: true })
+  permissionNames: string[];
+}

backend/src/modules/staff/dto/preview-staff-invite.dto.ts

@@ -0,0 +1,6 @@
+import { IsString } from 'class-validator';
+
+export class PreviewStaffInviteDto {
+  @IsString()
+  token: string;
+}

backend/src/modules/staff/dto/update-staff-member.dto.ts

@@ -0,0 +1,13 @@
+import { IsArray, IsOptional, IsString, MinLength } from 'class-validator';
+
+export class UpdateStaffMemberDto {
+  @IsOptional()
+  @IsString()
+  @MinLength(1)
+  name?: string;
+
+  @IsOptional()
+  @IsArray()
+  @IsString({ each: true })
+  permissionNames?: string[];
+}

backend/src/modules/staff/staff.controller.ts

@@ -0,0 +1,80 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  Param,
+  Patch,
+  Post,
+  Query,
+  Req,
+  UseGuards,
+} from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { AcceptStaffInviteDto } from './dto/accept-staff-invite.dto';
+import { InviteStaffDto } from './dto/invite-staff.dto';
+import { PreviewStaffInviteDto } from './dto/preview-staff-invite.dto';
+import { UpdateStaffMemberDto } from './dto/update-staff-member.dto';
+import { StaffService } from './staff.service';
+
+@ApiTags('staff')
+@ApiBearerAuth('JWT-auth')
+@Controller('staff')
+export class StaffController {
+  constructor(private readonly staffService: StaffService) {}
+
+  @Get('invitations/preview')
+  @ApiOperation({ summary: 'Preview invite info by token (public)' })
+  previewInvite(@Query() query: PreviewStaffInviteDto) {
+    return this.staffService.previewInvite(query.token);
+  }
+
+  @Post('invitations/accept')
+  @ApiOperation({ summary: 'Accept invite and activate account (public)' })
+  acceptInvite(@Body() dto: AcceptStaffInviteDto) {
+    return this.staffService.acceptInvite(dto);
+  }
+
+  @Get()
+  @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'List organization members (requires TAB_STAFF_READ or owner)' })
+  list(@Req() req: { user: { id: string; organizationId?: string } }) {
+    const organizationId = this.staffService.getOrganizationIdFromUser(req.user);
+    return this.staffService.list(req.user.id, organizationId);
+  }
+
+  @Post('invite')
+  @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Invite staff (requires TAB_STAFF_EDIT or owner)' })
+  invite(
+    @Req() req: { user: { id: string; organizationId?: string } },
+    @Body() dto: InviteStaffDto,
+  ) {
+    const organizationId = this.staffService.getOrganizationIdFromUser(req.user);
+    return this.staffService.invite(req.user.id, organizationId, dto);
+  }
+
+  @Patch('members/:membershipId')
+  @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Update staff member name and/or permissions' })
+  updateMember(
+    @Req() req: { user: { id: string; organizationId?: string } },
+    @Param('membershipId') membershipId: string,
+    @Body() dto: UpdateStaffMemberDto,
+  ) {
+    const organizationId = this.staffService.getOrganizationIdFromUser(req.user);
+    return this.staffService.updateMember(req.user.id, organizationId, membershipId, dto);
+  }
+
+  @Delete('members/:membershipId')
+  @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'Remove staff member from organization' })
+  removeMember(
+    @Req() req: { user: { id: string; organizationId?: string } },
+    @Param('membershipId') membershipId: string,
+  ) {
+    const organizationId = this.staffService.getOrganizationIdFromUser(req.user);
+    return this.staffService.removeMember(req.user.id, organizationId, membershipId);
+  }
+}

backend/src/modules/staff/staff.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { PrismaService } from '../../../prisma/prisma.service';
+import { StaffController } from './staff.controller';
+import { StaffService } from './staff.service';
+
+@Module({
+  controllers: [StaffController],
+  providers: [StaffService, PrismaService],
+})
+export class StaffModule {}

backend/src/modules/staff/staff.service.ts

@@ -0,0 +1,454 @@
+import {
+  BadRequestException,
+  ConflictException,
+  ForbiddenException,
+  Injectable,
+  NotFoundException,
+} from '@nestjs/common';
+import * as bcrypt from 'bcrypt';
+import { createHash, randomBytes } from 'crypto';
+import { PrismaService } from '../../../prisma/prisma.service';
+import { AcceptStaffInviteDto } from './dto/accept-staff-invite.dto';
+import { isUnlimitedSeats, normalizeTabPermissions } from '../../common/permissions';
+import { InviteStaffDto } from './dto/invite-staff.dto';
+import { UpdateStaffMemberDto } from './dto/update-staff-member.dto';
+
+@Injectable()
+export class StaffService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  getOrganizationIdFromUser(user: { organizationId?: string }) {
+    if (!user?.organizationId) {
+      throw new BadRequestException('Organization is not selected');
+    }
+    return user.organizationId;
+  }
+
+  async list(userId: string, organizationId: string) {
+    const actor = await this.getActorMembership(userId, organizationId);
+    if (!actor || !this.canViewStaff(actor)) {
+      throw new ForbiddenException('You do not have access to staff management');
+    }
+
+    const org = await this.prisma.organization.findUnique({
+      where: { id: organizationId },
+      include: { plan: true },
+    });
+    if (!org) {
+      throw new NotFoundException('Organization not found');
+    }
+
+    const [members, seatsUsed] = await Promise.all([
+      this.prisma.membership.findMany({
+        where: { organizationId },
+        include: {
+          user: { select: { id: true, email: true, name: true } },
+          permissions: { include: { permission: true } },
+          invitations: {
+            orderBy: { createdAt: 'desc' },
+            take: 1,
+          },
+        },
+        orderBy: [{ isOwner: 'desc' }, { createdAt: 'asc' }],
+      }),
+      this.prisma.membership.count({
+        where: {
+          organizationId,
+          OR: [{ isOwner: true }, { isActive: true }],
+        },
+      }),
+    ]);
+
+    const maxUsers = org.plan?.maxUsers ?? 0;
+    const unlimited = isUnlimitedSeats(maxUsers);
+
+    return {
+      success: true,
+      data: {
+        members: members.map((m) => ({
+          id: m.id,
+          userId: m.user.id,
+          email: m.user.email,
+          name: m.user.name,
+          isOwner: m.isOwner,
+          isActive: m.isOwner ? true : m.isActive,
+          invitationStatus: this.getInvitationStatus(m),
+          invitedAt: m.invitations[0]?.createdAt?.toISOString() || null,
+          acceptedAt: m.invitations[0]?.acceptedAt?.toISOString() || null,
+          permissions: m.isOwner
+            ? null
+            : m.permissions.map((p) => p.permission.name),
+        })),
+        seats: {
+          used: seatsUsed,
+          limit: unlimited ? null : maxUsers,
+          unlimited,
+        },
+      },
+    };
+  }
+
+  async invite(userId: string, organizationId: string, dto: InviteStaffDto) {
+    const actor = await this.getActorMembership(userId, organizationId);
+    if (!actor || !this.canEditStaff(actor)) {
+      throw new ForbiddenException('You cannot invite or manage staff');
+    }
+
+    const email = dto.email.trim().toLowerCase();
+    const normalizedPerms = normalizeTabPermissions(dto.permissionNames);
+
+    const permissionRows = await this.prisma.permission.findMany({
+      where: { name: { in: normalizedPerms } },
+      select: { id: true, name: true },
+    });
+    if (permissionRows.length !== normalizedPerms.length) {
+      const ok = new Set(permissionRows.map((p) => p.name));
+      const missing = normalizedPerms.filter((n) => !ok.has(n));
+      throw new BadRequestException(`Unknown or invalid permissions: ${missing.join(', ')}`);
+    }
+
+    const plainToken = this.generateInviteToken();
+    const tokenHash = this.hashInviteToken(plainToken);
+
+    const result = await this.prisma.$transaction(async (tx) => {
+      const org = await tx.organization.findUnique({
+        where: { id: organizationId },
+        include: { plan: true },
+      });
+      if (!org) {
+        throw new NotFoundException('Organization not found');
+      }
+
+      if (!org.plan) {
+        throw new BadRequestException(
+          'This organization has no active subscription. Please choose a plan before inviting staff.',
+        );
+      }
+
+      const maxUsers = org.plan.maxUsers;
+      const seatsUsed = await tx.membership.count({
+        where: {
+          organizationId,
+          OR: [{ isOwner: true }, { isActive: true }],
+        },
+      });
+      if (!isUnlimitedSeats(maxUsers) && seatsUsed >= maxUsers) {
+        throw new BadRequestException(
+          `Your plan allows ${maxUsers} team members. Remove a member or upgrade to add more.`,
+        );
+      }
+
+      const existingUser = await tx.user.findUnique({ where: { email } });
+      let targetUserId: string;
+
+      if (existingUser) {
+        if (existingUser.id === org.ownerId) {
+          throw new BadRequestException('Organization owner is already a member');
+        }
+        const dup = await tx.membership.findUnique({
+          where: {
+            userId_organizationId: {
+              userId: existingUser.id,
+              organizationId,
+            },
+          },
+        });
+        if (dup) {
+          throw new ConflictException('This user is already a member of this organization');
+        }
+        targetUserId = existingUser.id;
+      } else {
+        const created = await tx.user.create({
+          data: {
+            email,
+            name: dto.name.trim(),
+            passwordHash: null,
+          },
+        });
+        targetUserId = created.id;
+      }
+
+      const membership = await tx.membership.create({
+        data: {
+          userId: targetUserId,
+          organizationId,
+          isOwner: false,
+          isActive: existingUser ? true : false,
+        },
+      });
+
+      if (permissionRows.length > 0) {
+        await tx.membershipPermission.createMany({
+          data: permissionRows.map((p) => ({
+            membershipId: membership.id,
+            permissionId: p.id,
+          })),
+        });
+      }
+
+      let inviteUrl: string | null = null;
+      let invitationId: string | null = null;
+
+      if (!existingUser) {
+        const invitation = await tx.staffInvitation.create({
+          data: {
+            membershipId: membership.id,
+            invitedById: userId,
+            tokenHash,
+            expiresAt: this.getInviteExpiryDate(),
+          },
+        });
+        invitationId = invitation.id;
+        inviteUrl = this.buildInviteUrl(plainToken);
+      }
+
+      return {
+        membershipId: membership.id,
+        userId: targetUserId,
+        invitationId,
+        inviteUrl,
+        isPending: !existingUser,
+      };
+    });
+
+    return {
+      success: true,
+      data: {
+        membershipId: result.membershipId,
+        userId: result.userId,
+        email,
+        invitationId: result.invitationId,
+        invitationUrl: result.inviteUrl,
+        invitationStatus: result.isPending ? 'PENDING' : 'ACCEPTED',
+      },
+    };
+  }
+
+  async previewInvite(token: string) {
+    const invitation = await this.findValidInvitation(token);
+    const org = invitation.membership.organization;
+    const user = invitation.membership.user;
+
+    return {
+      success: true,
+      data: {
+        email: user.email,
+        name: user.name,
+        organizationName: org.name,
+        expiresAt: invitation.expiresAt.toISOString(),
+        status: invitation.acceptedAt ? 'ACCEPTED' : 'PENDING',
+      },
+    };
+  }
+
+  async acceptInvite(dto: AcceptStaffInviteDto) {
+    const invitation = await this.findValidInvitation(dto.token);
+
+    if (invitation.acceptedAt) {
+      throw new BadRequestException('This invitation has already been accepted');
+    }
+
+    const passwordHash = await bcrypt.hash(dto.password, 10);
+    const now = new Date();
+
+    await this.prisma.$transaction(async (tx) => {
+      await tx.user.update({
+        where: { id: invitation.membership.userId },
+        data: {
+          passwordHash,
+          name: dto.name.trim(),
+        },
+      });
+
+      await tx.membership.update({
+        where: { id: invitation.membershipId },
+        data: { isActive: true },
+      });
+
+      await tx.staffInvitation.update({
+        where: { id: invitation.id },
+        data: { acceptedAt: now },
+      });
+    });
+
+    return {
+      success: true,
+      data: {
+        email: invitation.membership.user.email,
+      },
+      message: 'Invitation accepted. You can now log in.',
+    };
+  }
+
+  async updateMember(
+    actorUserId: string,
+    organizationId: string,
+    membershipId: string,
+    dto: UpdateStaffMemberDto,
+  ) {
+    const actor = await this.getActorMembership(actorUserId, organizationId);
+    if (!actor || !this.canEditStaff(actor)) {
+      throw new ForbiddenException('You cannot edit staff');
+    }
+
+    const target = await this.prisma.membership.findFirst({
+      where: { id: membershipId, organizationId },
+      include: {
+        user: true,
+        permissions: { include: { permission: true } },
+      },
+    });
+
+    if (!target) {
+      throw new NotFoundException('Member not found');
+    }
+    if (target.isOwner) {
+      throw new ForbiddenException('Owner membership cannot be edited here');
+    }
+
+    if (dto.name !== undefined) {
+      await this.prisma.user.update({
+        where: { id: target.userId },
+        data: { name: dto.name.trim() },
+      });
+    }
+
+    if (dto.permissionNames !== undefined) {
+      const normalizedPerms = normalizeTabPermissions(dto.permissionNames);
+      const permissionRows = await this.prisma.permission.findMany({
+        where: { name: { in: normalizedPerms } },
+        select: { id: true, name: true },
+      });
+      if (permissionRows.length !== normalizedPerms.length) {
+        const ok = new Set(permissionRows.map((p) => p.name));
+        const missing = normalizedPerms.filter((n) => !ok.has(n));
+        throw new BadRequestException(`Unknown or invalid permissions: ${missing.join(', ')}`);
+      }
+
+      await this.prisma.$transaction([
+        this.prisma.membershipPermission.deleteMany({ where: { membershipId: target.id } }),
+        ...(permissionRows.length
+          ? [
+              this.prisma.membershipPermission.createMany({
+                data: permissionRows.map((p) => ({
+                  membershipId: target.id,
+                  permissionId: p.id,
+                })),
+              }),
+            ]
+          : []),
+      ]);
+    }
+
+    return { success: true, message: 'Member updated' };
+  }
+
+  async removeMember(actorUserId: string, organizationId: string, membershipId: string) {
+    const actor = await this.getActorMembership(actorUserId, organizationId);
+    if (!actor || !this.canEditStaff(actor)) {
+      throw new ForbiddenException('You cannot remove staff');
+    }
+
+    const target = await this.prisma.membership.findFirst({
+      where: { id: membershipId, organizationId },
+    });
+
+    if (!target) {
+      throw new NotFoundException('Member not found');
+    }
+    if (target.isOwner) {
+      throw new ForbiddenException('Cannot remove the organization owner');
+    }
+
+    await this.prisma.membership.delete({ where: { id: membershipId } });
+
+    return { success: true, message: 'Member removed' };
+  }
+
+  private async getActorMembership(userId: string, organizationId: string) {
+    return this.prisma.membership.findFirst({
+      where: { userId, organizationId },
+      include: {
+        permissions: { include: { permission: true } },
+        organization: { select: { planId: true } },
+      },
+    });
+  }
+
+  private getInvitationStatus(m: {
+    isOwner: boolean;
+    isActive: boolean;
+    invitations: { acceptedAt: Date | null; revokedAt: Date | null; expiresAt: Date }[];
+  }): 'ACTIVE' | 'PENDING' | 'EXPIRED' {
+    if (m.isOwner || m.isActive) return 'ACTIVE';
+    const invitation = m.invitations[0];
+    if (!invitation) return 'EXPIRED';
+    if (invitation.acceptedAt || invitation.revokedAt) return 'ACTIVE';
+    return invitation.expiresAt.getTime() > Date.now() ? 'PENDING' : 'EXPIRED';
+  }
+
+  private generateInviteToken(): string {
+    return randomBytes(32).toString('hex');
+  }
+
+  private hashInviteToken(token: string): string {
+    return createHash('sha256').update(token).digest('hex');
+  }
+
+  private getInviteExpiryDate(): Date {
+    const d = new Date();
+    d.setDate(d.getDate() + 7);
+    return d;
+  }
+
+  private buildInviteUrl(token: string): string {
+    const appUrl = process.env.FRONTEND_URL || 'http://localhost:3001';
+    return `${appUrl}/accept-invite?token=${encodeURIComponent(token)}`;
+  }
+
+  private async findValidInvitation(token: string) {
+    const invitation = await this.prisma.staffInvitation.findUnique({
+      where: { tokenHash: this.hashInviteToken(token) },
+      include: {
+        membership: {
+          include: {
+            user: { select: { id: true, email: true, name: true } },
+            organization: { select: { id: true, name: true } },
+          },
+        },
+      },
+    });
+
+    if (!invitation) {
+      throw new NotFoundException('Invitation not found');
+    }
+    if (invitation.revokedAt) {
+      throw new BadRequestException('Invitation has been revoked');
+    }
+    if (invitation.expiresAt.getTime() <= Date.now()) {
+      throw new BadRequestException('Invitation has expired');
+    }
+    return invitation;
+  }
+
+  private canViewStaff(m: {
+    isOwner: boolean;
+    organization?: { planId: string | null };
+    permissions: { permission: { name: string } }[];
+  }): boolean {
+    if (m.isOwner) return true;
+    return m.permissions.some(
+      (p) =>
+        p.permission.name === 'TAB_STAFF_READ' || p.permission.name === 'TAB_STAFF_EDIT',
+    );
+  }
+
+  private canEditStaff(m: {
+    isOwner: boolean;
+    organization?: { planId: string | null };
+    permissions: { permission: { name: string } }[];
+  }): boolean {
+    if (m.isOwner) return Boolean(m.organization?.planId);
+    return m.permissions.some((p) => p.permission.name === 'TAB_STAFF_EDIT');
+  }
+}

backend/tsconfig.json

@@ -1,5 +1,6 @@
 {
   "compilerOptions": {
+    "types": ["node", "jest"],
     "module": "nodenext",
     "moduleResolution": "nodenext",
     "resolvePackageJsonExports": true,

frontend/Dockerfile

@@ -1,72 +1,53 @@
-# Build stage
-FROM node:18-alpine AS builder
+# Build stage — produces `.next/standalone` (see next.config.ts output: standalone)
+FROM node:20-alpine AS builder
 
 WORKDIR /app
 
-# Copy package files
 COPY package*.json ./
 RUN npm ci
 
-# Copy source code
 COPY . .
 
-# Set build-time environment variables
+ARG NEXT_PUBLIC_API_URL
+ARG NEXT_PUBLIC_APP_URL
+ARG NEXT_PUBLIC_APP_NAME
+
 ENV NEXT_TELEMETRY_DISABLED=1
 ENV NODE_ENV=production
+ENV NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}
+ENV NEXT_PUBLIC_APP_URL=${NEXT_PUBLIC_APP_URL}
+ENV NEXT_PUBLIC_APP_NAME=${NEXT_PUBLIC_APP_NAME}
 
-# Build Next.js application
 RUN npm run build
 
-# Production stage
-FROM node:18-alpine
+# Production — minimal runtime using Next.js standalone bundle
+FROM node:20-alpine AS runner
+
+RUN apk add --no-cache dumb-init
 
 WORKDIR /app
 
-# Install dumb-init for proper signal handling
-RUN apk add --no-cache dumb-init
-
-# Create non-root user
 RUN addgroup -g 1001 -S nodejs && \
     adduser -S dyolink -u 1001
 
-# Copy package files
-COPY package*.json ./
+ENV NODE_ENV=production
+ENV PORT=3000
+ENV HOSTNAME=0.0.0.0
 
-# Install production dependencies only
-RUN npm ci --only=production && \
-    npm cache clean --force
-
-# Copy built application
-COPY --from=builder /app/.next ./.next
 COPY --from=builder /app/public ./public
-COPY --from=builder /app/next.config.js ./next.config.js
-COPY --from=builder /app/package.json ./package.json
+COPY --from=builder --chown=dyolink:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=dyolink:nodejs /app/.next/static ./.next/static
 
-# Create logs directory
-RUN mkdir -p /app/logs && \
-    chown -R dyolink:nodejs /app
+COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
 
-# Set ownership
-RUN chown -R dyolink:nodejs /app
-
-# Switch to non-root user
 USER dyolink
 
-# Health check
-HEALTHCHECK --interval=30s --timeout=5s --start-period=40s --retries=3 \
-  CMD node -e "require('http').get('http://localhost:3000', (r) => {if(r.statusCode!==200)throw new Error()})" || exit 1
-
 EXPOSE 3000
 
-ENV PORT=3000
-ENV HOSTNAME="0.0.0.0"
-ENV NODE_ENV=production
+HEALTHCHECK --interval=30s --timeout=5s --start-period=40s --retries=3 \
+  CMD node -e "require('http').get('http://127.0.0.1:3000/', (r) => {if(r.statusCode!==200)process.exit(1)})"
 
-# Copy entrypoint script
-COPY docker-entrypoint.sh /usr/local/bin/
-RUN chmod +x /usr/local/bin/docker-entrypoint.sh
-
-# Use dumb-init for signal handling
 ENTRYPOINT ["dumb-init", "--", "docker-entrypoint.sh"]
 
-CMD ["npm", "start"]
+CMD ["node", "server.js"]

frontend/README.md

@@ -1,36 +1,63 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# Dyolink — Frontend (Next.js)
 
-## Getting Started
+## Prerequisites
 
-First, run the development server:
+- **Node.js 20+** and **npm**
+
+## First-time setup
+
+1. **Clone the monorepo** and go to the frontend app:
+
+   ```bash
+   git clone <repository-url> dyolink
+   cd dyolink/frontend
+   ```
+
+2. **Install dependencies**
+
+   ```bash
+   npm install
+   ```
+
+3. **Environment**
+
+   Create **`.env.local`** in this folder (not committed to git) with the public URLs your browser will use:
+
+   ```env
+   NEXT_PUBLIC_APP_URL=http://localhost:3001
+   NEXT_PUBLIC_API_URL=http://localhost:3000/api
+   NEXT_PUBLIC_APP_NAME=Dyolink
+   ```
+
+   - Adjust **`NEXT_PUBLIC_API_URL`** if the Nest API runs on another host/port.
+   - These values are baked in at **build time** for production images; for local dev, restart `npm run dev` after changing them.
+
+## Run (development)
 
 ```bash
 npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+Open **`http://localhost:3001`** (dev server uses port **3001** so it does not clash with the API on 3000).
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+Ensure the backend is running and `NEXT_PUBLIC_API_URL` matches its base URL (including `/api` if your API is mounted there).
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+## After pulling latest `main`
 
-## Learn More
+```bash
+git pull
+npm install
+```
 
-To learn more about Next.js, take a look at the following resources:
+## Useful commands
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+| Command | Purpose |
+|--------|---------|
+| `npm run dev` | Development server (port 3001) |
+| `npm run build` | Production build |
+| `npm run start` | Serve production build (port 3000 — used inside Docker) |
+| `npm run lint` | ESLint |
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+## Docker
 
-## Deploy on Vercel
-
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
-
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+Image build and build-args (`NEXT_PUBLIC_*`) are documented in the **repository root `README.md`**.

frontend/next.config.ts

@@ -1,6 +1,17 @@
 import type { NextConfig } from "next";
 
-// frontend/next.config.js
+function publicAppHostname(): string | null {
+  const url = process.env.NEXT_PUBLIC_APP_URL;
+  if (!url) return null;
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return null;
+  }
+}
+
+const appHost = publicAppHostname();
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   // Enable React strict mode
@@ -9,11 +20,19 @@ const nextConfig = {
   // Disable x-powered-by header for security
   poweredByHeader: false,
   
-  // Configure image domains if needed
+  // Configure allowed remote image sources (hostname derived from NEXT_PUBLIC_APP_URL at build time)
   images: {
-    domains: process.env.NODE_ENV === 'production' 
-      ? ['yourdomain.com'] 
-      : ['localhost'],
+    remotePatterns: [
+      { protocol: "http", hostname: "localhost" },
+      ...(appHost
+        ? [
+            { protocol: "http" as const, hostname: appHost },
+            { protocol: "https" as const, hostname: appHost },
+          ]
+        : []),
+      { protocol: "https", hostname: "dyolink.com" },
+      { protocol: "https", hostname: "www.dyolink.com" },
+    ],
   },
   
   // Environment variables that will be available at build time

frontend/package.json

@@ -5,7 +5,7 @@
   "scripts": {
     "dev": "next dev -p 3001",
     "build": "next build",
-    "start": "next start -p 3001",
+    "start": "next start -p 3000",
     "lint": "next lint"
   },
   "dependencies": {

frontend/src/app/(dashboard)/appointments/page.tsx

@@ -0,0 +1,10 @@
+export default function AppointmentsPage() {
+  return (
+    <div className="space-y-3">
+      <h1 className="text-2xl font-semibold text-text-primary">Appointments</h1>
+      <p className="text-sm text-text-secondary">
+        Appointments module is coming soon.
+      </p>
+    </div>
+  );
+}

frontend/src/app/(dashboard)/billing/page.tsx

@@ -2,9 +2,11 @@
 'use client';
 import { useState } from 'react';
 import { Search, Filter, Plus } from 'lucide-react';
-import { Button } from '@/components/ui/Button';
-import { Input } from '@/components/ui/Input';
-import { Badge } from '@/components/ui/Badge';
+import { Button } from '@/components/ui/common/Button';
+import { Input } from '@/components/ui/common/Input';
+import { Badge } from '@/components/ui/common/Badge';
+import { useAuth } from '@/lib/hooks/useAuth';
+import { hasPermission } from '@/shared/permissions';
 // Mock data matching your design
 const invoices = [
     { id: '#123456', patient: 'Ali Rahmani', date: '24/9/2026', service: 'Hygiene', amount: 300, paid: 0, status: 'unpaid' },
@@ -25,8 +27,10 @@ interface StatCardProps {
     color: StatCardColor;
 }
 export default function BillingPage() {
+    const { currentOrganization } = useAuth();
     const [search, setSearch] = useState('');
     const [statusFilter, setStatusFilter] = useState('all');
+    const canEditBilling = hasPermission(currentOrganization, 'TAB_BILLING_EDIT');
     const stats = {
         total: { count: 235, amount: 80900 },
         unpaid: { count: 30, amount: 2800 },
@@ -38,7 +42,12 @@ export default function BillingPage() {
             {/* Header */}
             <div className="flex justify-between items-center">
                 <h1 className="text-2xl font-semibold text-text-primary">Billing</h1>
-                <Button variant="primary" className="flex items-center gap-2">
+                <Button
+                    variant="primary"
+                    className="flex items-center gap-2"
+                    disabled={!canEditBilling}
+                    title={!canEditBilling ? 'Read-only access for this organization.' : undefined}
+                >
                     <Plus className="h-4 w-4 icon-flat" />
                     New Invoice
                 </Button>
@@ -158,7 +167,11 @@ export default function BillingPage() {
                                     </Badge>
                                 </td>
                                 <td className="px-6 py-4">
-                                    <button className="text-primary hover:opacity-90 text-sm">
+                                    <button
+                                        className={`text-sm ${canEditBilling ? 'text-primary hover:opacity-90' : 'text-text-muted cursor-not-allowed'}`}
+                                        disabled={!canEditBilling}
+                                        title={!canEditBilling ? 'Read-only access for this organization.' : undefined}
+                                    >
                                         Edit
                                     </button>
                                 </td>

frontend/src/app/(dashboard)/lab/page.tsx

@@ -0,0 +1,10 @@
+export default function LabPage() {
+  return (
+    <div className="space-y-3">
+      <h1 className="text-2xl font-semibold text-text-primary">Lab Management</h1>
+      <p className="text-sm text-text-secondary">
+        Lab management module is coming soon.
+      </p>
+    </div>
+  );
+}

frontend/src/app/(dashboard)/layout.tsx

@@ -1,15 +1,21 @@
 'use client';
 
-import { useEffect } from 'react';
-import { useRouter } from 'next/navigation';
+import { memo, useEffect } from 'react';
+import { usePathname, useRouter } from 'next/navigation';
 import { useAuth } from '@/lib/hooks/useAuth';
-import Sidebar from '@/components/ui/Sidebar';
-import { ThemeToggle } from '@/components/ui/ThemeToggle';
-import { LogOut } from 'lucide-react';
+import Sidebar from '@/components/ui/common/Sidebar';
+import { ThemeToggle } from '@/components/ui/common/ThemeToggle';
+import { DashboardAccountMenu } from '@/components/ui/dashboard/DashboardAccountMenu';
+import {
+  firstAccessibleDashboardPath,
+  getRequiredReadPermissionForPath,
+  hasPermission,
+} from '@/shared/permissions';
 
 export default function DashboardLayout({ children }: { children: React.ReactNode }) {
-  const { user, currentOrganization, isAuthReady, logout } = useAuth();
+  const { user, currentOrganization, isAuthReady } = useAuth();
   const router = useRouter();
+  const pathname = usePathname();
 
   // ✅ AUTH GUARD (runs once per navigation group)
   useEffect(() => {
@@ -24,7 +30,12 @@ export default function DashboardLayout({ children }: { children: React.ReactNod
       router.replace('/select-organization');
       return;
     }
-  }, [isAuthReady, user, currentOrganization, router]);
+
+    const required = getRequiredReadPermissionForPath(pathname);
+    if (required && !hasPermission(currentOrganization, required)) {
+      router.replace(firstAccessibleDashboardPath(currentOrganization));
+    }
+  }, [isAuthReady, user, currentOrganization, router, pathname]);
 
   // ✅ LOADING ONLY FOR INITIAL LOAD
   if (!isAuthReady) {
@@ -48,21 +59,7 @@ export default function DashboardLayout({ children }: { children: React.ReactNod
       <Sidebar />
 
       <div className="flex-1 flex flex-col">
-        <header className="flex justify-between px-6 py-4 border-b border-border/70 backdrop-blur-sm">
-          <h2 className="text-lg font-medium">{currentOrganization.name}</h2>
-
-          <div className="flex items-center gap-4">
-            <ThemeToggle />
-            <span className="text-sm text-text-secondary">{user.name}</span>
-            <button
-              onClick={logout}
-              className="inline-flex items-center gap-2 text-sm text-text-secondary hover:text-text-primary transition-colors"
-            >
-              <LogOut className="w-4 h-4 icon-flat" />
-              Logout
-            </button>
-          </div>
-        </header>
+        <DashboardHeader organizationName={currentOrganization.name} />
 
         <main className="p-6 flex-1 overflow-y-auto">
           <div className="surface-panel p-6 min-h-full">
@@ -72,4 +69,21 @@ export default function DashboardLayout({ children }: { children: React.ReactNod
       </div>
     </div>
   );
-}
+}
+
+const DashboardHeader = memo(function DashboardHeader({
+  organizationName,
+}: {
+  organizationName: string;
+}) {
+  return (
+    <header className="relative z-40 h-[71px] flex justify-between items-center gap-4 px-6 border-b border-border/70 backdrop-blur-sm">
+      <h2 className="text-lg font-medium truncate min-w-0">{organizationName}</h2>
+
+      <div className="flex items-center gap-3 shrink-0">
+        <ThemeToggle />
+        <DashboardAccountMenu />
+      </div>
+    </header>
+  );
+});

frontend/src/app/(dashboard)/patients/page.tsx

@@ -0,0 +1,236 @@
+'use client';
+
+import { useEffect, useMemo, useState } from 'react';
+import { Plus } from 'lucide-react';
+import { Button } from '@/components/ui/common/Button';
+import { patientsApi } from '@/lib/api/patients';
+import { useAuth } from '@/lib/hooks/useAuth';
+import { hasPermission } from '@/shared/permissions';
+import {
+  CreatePatientInput,
+  CreateTreatmentHistoryInput,
+  Patient,
+  TreatmentHistoryItem,
+} from '@/types/patient';
+import { PatientSearchSelect } from '../../../components/ui/patient/PatientSearchSelect';
+import { CreatePatientModal } from '../../../components/ui/patient/CreatePatientModal';
+import { PatientSummaryCard } from '../../../components/ui/patient/PatientSummaryCard';
+import { TreatmentHistoryPreview } from '../../../components/ui/patient/TreatmentHistoryPreview';
+
+const EMPTY_PATIENT_FORM: CreatePatientInput = {
+  firstName: '',
+  lastName: '',
+  phone: '',
+  email: '',
+};
+
+export default function PatientsPage() {
+  const { currentOrganization } = useAuth();
+  const [search, setSearch] = useState('');
+  const [patients, setPatients] = useState<Patient[]>([]);
+  const [selectedPatient, setSelectedPatient] = useState<Patient | undefined>();
+  const [treatments, setTreatments] = useState<TreatmentHistoryItem[]>([]);
+  const [loadingPatients, setLoadingPatients] = useState(false);
+  const [loadingTreatments, setLoadingTreatments] = useState(false);
+  const [isCreateOpen, setIsCreateOpen] = useState(false);
+  const [savingPatient, setSavingPatient] = useState(false);
+  const [savingTreatment, setSavingTreatment] = useState(false);
+  const [patientForm, setPatientForm] = useState<CreatePatientInput>(EMPTY_PATIENT_FORM);
+  const [errorMessage, setErrorMessage] = useState<string>('');
+  const [successMessage, setSuccessMessage] = useState<string>('');
+  const canEditPatients = hasPermission(currentOrganization, 'TAB_PATIENTS_EDIT');
+
+  const sortedPatients = useMemo(
+    () =>
+      [...patients].sort((a, b) =>
+        `${a.firstName} ${a.lastName}`.localeCompare(`${b.firstName} ${b.lastName}`),
+      ),
+    [patients],
+  );
+
+  useEffect(() => {
+    const timeout = setTimeout(() => {
+      void loadPatients(search);
+    }, 300);
+    return () => clearTimeout(timeout);
+  }, [search]);
+
+  useEffect(() => {
+    void loadPatients('');
+  }, []);
+
+  useEffect(() => {
+    if (!successMessage) {
+      return;
+    }
+
+    const timeout = setTimeout(() => {
+      setSuccessMessage('');
+    }, 3000);
+
+    return () => clearTimeout(timeout);
+  }, [successMessage]);
+
+  async function loadPatients(q: string) {
+    setLoadingPatients(true);
+    setErrorMessage('');
+    try {
+      const response = await patientsApi.list({ q, page: 1, limit: 25 });
+      const items = response.data.items;
+      setPatients(items);
+
+      if (selectedPatient) {
+        const freshSelected = items.find((item) => item.id === selectedPatient.id);
+        setSelectedPatient(freshSelected);
+      }
+    } catch (error: any) {
+      const message = Array.isArray(error?.message) ? error.message.join(', ') : error?.message;
+      setErrorMessage(message || 'Failed to load patients.');
+    } finally {
+      setLoadingPatients(false);
+    }
+  }
+
+  async function loadTreatments(patientId: string) {
+    setLoadingTreatments(true);
+    setErrorMessage('');
+    try {
+      const response = await patientsApi.listTreatments(patientId);
+      setTreatments(response.data);
+    } catch (error: any) {
+      const message = Array.isArray(error?.message) ? error.message.join(', ') : error?.message;
+      setErrorMessage(message || 'Failed to load treatment history.');
+    } finally {
+      setLoadingTreatments(false);
+    }
+  }
+
+  async function handleCreatePatient() {
+    setSavingPatient(true);
+    setErrorMessage('');
+    setSuccessMessage('');
+    try {
+      const response = await patientsApi.create(patientForm);
+      setIsCreateOpen(false);
+      setPatientForm(EMPTY_PATIENT_FORM);
+      await loadPatients(search);
+      setSelectedPatient(response.data);
+      await loadTreatments(response.data.id);
+      setSuccessMessage(
+        `Patient ${response.data.firstName} ${response.data.lastName} was saved successfully.`,
+      );
+    } catch (error: any) {
+      const message = Array.isArray(error?.message) ? error.message.join(', ') : error?.message;
+      setErrorMessage(message || 'Failed to save patient.');
+    } finally {
+      setSavingPatient(false);
+    }
+  }
+
+  async function handleQuickAddTreatment() {
+    if (!selectedPatient) {
+      return;
+    }
+
+    const payload: CreateTreatmentHistoryInput = {
+      title: 'Initial consultation',
+      status: 'scheduled',
+      treatmentAt: new Date().toISOString(),
+      notes: 'Created from quick action on patients page.',
+    };
+
+    setSavingTreatment(true);
+    setErrorMessage('');
+    setSuccessMessage('');
+    try {
+      await patientsApi.addTreatment(selectedPatient.id, payload);
+      await loadTreatments(selectedPatient.id);
+      setSuccessMessage('Treatment entry added successfully.');
+    } catch (error: any) {
+      const message = Array.isArray(error?.message) ? error.message.join(', ') : error?.message;
+      setErrorMessage(message || 'Failed to add treatment entry.');
+    } finally {
+      setSavingTreatment(false);
+    }
+  }
+
+  return (
+    <div className="relative space-y-6 pb-20">
+      <div className="flex items-center justify-between">
+        <h1 className="text-2xl font-semibold text-text-primary">Patients</h1>
+        <Button
+          variant="primary"
+          className="flex items-center gap-2"
+          disabled={!canEditPatients}
+          onClick={() => {
+            if (!canEditPatients) return;
+            setIsCreateOpen(true);
+          }}
+          title={!canEditPatients ? 'Read-only access for this organization.' : undefined}
+        >
+          <Plus className="h-4 w-4 icon-flat" />
+          New Patient
+        </Button>
+      </div>
+
+      <CreatePatientModal
+        isOpen={isCreateOpen}
+        formData={patientForm}
+        onChange={(patch) => setPatientForm((prev) => ({ ...prev, ...patch }))}
+        onSubmit={handleCreatePatient}
+        onClose={() => setIsCreateOpen(false)}
+        loading={savingPatient}
+      />
+
+      <div className="grid grid-cols-1 xl:grid-cols-3 gap-6">
+        <div className="xl:col-span-1">
+          <PatientSearchSelect
+            search={search}
+            onSearchChange={setSearch}
+            patients={sortedPatients}
+            selectedPatientId={selectedPatient?.id}
+            onSelectPatient={(patient) => {
+              setSelectedPatient(patient);
+              void loadTreatments(patient.id);
+            }}
+            loading={loadingPatients}
+          />
+        </div>
+
+        <div className="xl:col-span-2 space-y-4">
+          <PatientSummaryCard patient={selectedPatient} />
+          <div className="flex">
+            <Button
+              variant="secondary"
+              disabled={!selectedPatient || !canEditPatients}
+              isLoading={savingTreatment}
+              onClick={() => {
+                if (!canEditPatients) return;
+                void handleQuickAddTreatment();
+              }}
+              title={!canEditPatients ? 'Read-only access for this organization.' : undefined}
+            >
+              Add Quick Treatment Entry
+            </Button>
+          </div>
+          <TreatmentHistoryPreview items={treatments} loading={loadingTreatments} />
+        </div>
+      </div>
+
+      {(errorMessage || successMessage) && (
+        <div className="absolute bottom-0 left-0 right-0 z-10 w-full">
+          {errorMessage && (
+            <div className="rounded-[var(--radius-sm)] border border-red-500/50 bg-red-500/10 px-3 py-2 text-sm text-red-300 shadow-lg">
+              {errorMessage}
+            </div>
+          )}
+          {successMessage && (
+            <div className="rounded-[var(--radius-sm)] border border-emerald-500/50 bg-emerald-500/10 px-3 py-2 text-sm text-emerald-300 shadow-lg">
+              {successMessage}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/app/(dashboard)/reports/page.tsx

@@ -0,0 +1,10 @@
+export default function ReportsPage() {
+  return (
+    <div className="space-y-3">
+      <h1 className="text-2xl font-semibold text-text-primary">Reports</h1>
+      <p className="text-sm text-text-secondary">
+        Reports module is coming soon.
+      </p>
+    </div>
+  );
+}

frontend/src/app/(dashboard)/settings/account/page.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+import Link from 'next/link';
+
+export default function AccountSettingsPage() {
+  return (
+    <div className="space-y-6">
+      <div>
+        <Link
+          href="/today"
+          className="text-sm text-primary hover:opacity-90"
+        >
+          ← Back to app
+        </Link>
+        <h1 className="text-2xl font-semibold text-text-primary mt-4">Account</h1>
+        <p className="text-text-secondary text-sm mt-2">
+          Profile and security settings for your login.
+        </p>
+      </div>
+
+      <div className="surface-card p-6 space-y-3">
+        <p className="text-sm text-text-secondary">
+          Password change and profile editing will be wired here next (e.g. invite
+          flow, reset password).
+        </p>
+      </div>
+    </div>
+  );
+}

frontend/src/app/(dashboard)/settings/organizations/page.tsx

@@ -0,0 +1,20 @@
+'use client';
+
+import Link from 'next/link';
+import { OrganizationSelectorContent } from '@/components/ui/organization/OrganizationSelectorContent';
+
+export default function DashboardOrganizationsSettingsPage() {
+  return (
+    <div className="space-y-6">
+      <div>
+        <Link
+          href="/today"
+          className="text-sm text-primary hover:opacity-90"
+        >
+          ← Back to app
+        </Link>
+      </div>
+      <OrganizationSelectorContent />
+    </div>
+  );
+}

frontend/src/app/(dashboard)/settings/subscriptions/page.tsx

@@ -0,0 +1,200 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import Link from 'next/link';
+import { useRouter } from 'next/navigation';
+import { useAuth } from '@/lib/hooks/useAuth';
+import { authApi } from '@/lib/api/auth';
+import type { SubscriptionAlertData } from '@/types/subscription';
+
+const PLAN_OPTIONS = [
+  { id: 'solo', name: 'Solo', maxUsers: 1, price: 19 },
+  { id: 'small', name: 'Small', maxUsers: 5, price: 49 },
+  { id: 'medium', name: 'Medium', maxUsers: 10, price: 89 },
+  { id: 'large', name: 'Large', maxUsers: 15, price: 129 },
+  { id: 'enterprise', name: 'Enterprise', maxUsers: null, price: 199 },
+] as const;
+
+export default function SubscriptionsSettingsPage() {
+  const { currentOrganization } = useAuth();
+  const router = useRouter();
+  const [alert, setAlert] = useState<SubscriptionAlertData | null>(null);
+  const [selectedPlanId, setSelectedPlanId] = useState<string>(PLAN_OPTIONS[0].id);
+  const [purchaseNotice, setPurchaseNotice] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (currentOrganization && !currentOrganization.isOwner) {
+      router.replace('/today');
+    }
+  }, [currentOrganization, router]);
+
+  useEffect(() => {
+    if (!currentOrganization?.isOwner) return;
+    void authApi.getSubscriptionAlert().then((r) => {
+      if (r.success) setAlert(r.data);
+    });
+  }, [currentOrganization?.id, currentOrganization?.isOwner]);
+
+  if (!currentOrganization) {
+    return (
+      <p className="text-text-secondary text-sm">Loading...</p>
+    );
+  }
+
+  if (!currentOrganization.isOwner) {
+    return (
+      <p className="text-text-secondary text-sm">Redirecting...</p>
+    );
+  }
+
+  const plan = currentOrganization.plan;
+  const hasActiveSubscription = Boolean(plan);
+  const selectedPlan = PLAN_OPTIONS.find((option) => option.id === selectedPlanId);
+  const maxUsers = plan?.maxUsers;
+  const isUnlimited = typeof maxUsers === 'number' && maxUsers >= 999999;
+  const seatsUsed = alert?.seatsUsed;
+  const seatsRemaining =
+    typeof seatsUsed === 'number' && typeof maxUsers === 'number' && !isUnlimited
+      ? Math.max(0, maxUsers - seatsUsed)
+      : null;
+  const daysUntilPlanEnd = alert?.daysUntilPlanEnd ?? null;
+  const planDayTone =
+    daysUntilPlanEnd == null
+      ? 'text-text-primary'
+      : daysUntilPlanEnd > 20
+        ? 'text-emerald-400'
+        : daysUntilPlanEnd >= 10
+          ? 'text-amber-300'
+          : 'text-red-400';
+
+  return (
+    <div className="space-y-6">
+      <div>
+        <Link
+          href="/today"
+          className="text-sm text-primary hover:opacity-90"
+        >
+          ← Back to app
+        </Link>
+        <h1 className="text-2xl font-semibold text-text-primary mt-4">Subscriptions</h1>
+        <p className="text-text-secondary text-sm mt-2">
+          Your DyoLink workspace plan and seats for{' '}
+          <span className="text-text-primary font-medium">{currentOrganization.name}</span>.
+          Clinic and lab income tracking stays under the sidebar{' '}
+          <span className="text-text-primary">Billing</span> tab.
+        </p>
+      </div>
+
+      <div className="surface-card p-6 space-y-4">
+        {!hasActiveSubscription && (
+          <div className="rounded-[var(--radius-md)] border border-amber-500/30 bg-amber-500/10 p-4">
+            <p className="text-sm text-amber-200">
+              This organization has no active subscription. Select a plan below to start
+              the purchase process.
+            </p>
+          </div>
+        )}
+
+        <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-5">
+          <div>
+            <p className="text-xs text-text-muted uppercase tracking-wide">Current plan</p>
+            <p className="text-lg font-medium text-text-primary capitalize">
+              {plan?.name ?? '—'}
+            </p>
+          </div>
+          <div>
+            <p className="text-xs text-text-muted uppercase tracking-wide">Plan price</p>
+            <p className="text-lg font-medium text-text-primary">
+              {typeof plan?.price === 'number' ? `$${plan.price}` : '—'}
+            </p>
+          </div>
+          <div>
+            <p className="text-xs text-text-muted uppercase tracking-wide">Seats used</p>
+            <p className="text-lg font-medium text-text-primary">
+              {typeof seatsUsed === 'number' ? seatsUsed : '—'}
+              {typeof maxUsers === 'number' ? ` / ${isUnlimited ? 'Unlimited' : maxUsers}` : ''}
+            </p>
+          </div>
+          <div>
+            <p className="text-xs text-text-muted uppercase tracking-wide">Seats remaining</p>
+            <p className="text-lg font-medium text-text-primary">
+              {isUnlimited ? 'Unlimited' : seatsRemaining ?? '—'}
+            </p>
+          </div>
+          <div>
+            <p className="text-xs text-text-muted uppercase tracking-wide">Days remaining</p>
+            <p className={`text-lg font-medium ${planDayTone}`}>
+              {daysUntilPlanEnd ?? '—'}
+            </p>
+          </div>
+        </div>
+
+        {alert?.showWarning && (
+          <div className="text-sm text-text-secondary space-y-1">
+            {alert.noActiveSubscription && (
+              <p>No active subscription for this organization.</p>
+            )}
+            {alert.trialExpired && (
+              <p>Trial period has ended. Choose a plan when checkout is available.</p>
+            )}
+            {!alert.trialExpired && alert.trialEndingSoon && (
+              <p>
+                Trial ends in {alert.daysUntilTrialEnd ?? '—'} day(s).
+              </p>
+            )}
+            {!alert.trialExpired && !alert.trialEndingSoon && alert.seatsLow && (
+              <p>Seat usage is high for this organization.</p>
+            )}
+          </div>
+        )}
+
+        <div className="space-y-3 pt-2">
+          <p className="text-sm text-text-secondary">
+            Choose a plan to continue. Purchase integration is not active yet, so this
+            currently prepares the selection step only.
+          </p>
+          <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+            {PLAN_OPTIONS.map((option) => {
+              const selected = selectedPlanId === option.id;
+              return (
+                <button
+                  key={option.id}
+                  type="button"
+                  onClick={() => setSelectedPlanId(option.id)}
+                  className={`rounded-[var(--radius-md)] border p-4 text-left transition-colors ${
+                    selected
+                      ? 'border-primary/70 bg-primary-soft'
+                      : 'border-border hover:border-border-strong'
+                  }`}
+                >
+                  <p className="text-base font-medium text-text-primary">{option.name}</p>
+                  <p className="text-sm text-text-secondary mt-1">
+                    {option.maxUsers == null ? 'Unlimited seats' : `${option.maxUsers} seats`}
+                  </p>
+                  <p className="text-sm text-text-secondary mt-1">${option.price} / month</p>
+                </button>
+              );
+            })}
+          </div>
+          <button
+            type="button"
+            className="inline-flex items-center justify-center rounded-[var(--radius-md)] bg-primary px-4 py-2 text-sm font-medium text-white hover:opacity-90 disabled:opacity-60"
+            onClick={() => {
+              const selectedPlanLabel = selectedPlan?.name ?? 'the selected plan';
+              setPurchaseNotice(
+                `Purchase flow will be enabled soon. ${selectedPlanLabel} is selected and ready for checkout setup.`,
+              );
+            }}
+          >
+            Start purchase process
+          </button>
+          {purchaseNotice && (
+            <div className="rounded-[var(--radius-md)] border border-emerald-500/30 bg-emerald-500/10 px-4 py-3">
+              <p className="text-sm text-emerald-200">{purchaseNotice}</p>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/src/app/(dashboard)/staff/components/staffPermissions.ts

@@ -0,0 +1,44 @@
+/** Feature groups for staff invite/edit UI — matches backend seed */
+export const STAFF_FEATURE_GROUPS = [
+  { label: 'Today', read: 'TAB_TODAY_READ', edit: 'TAB_TODAY_EDIT' },
+  { label: 'Staff', read: 'TAB_STAFF_READ', edit: 'TAB_STAFF_EDIT' },
+  { label: 'Labs / Clinics', read: 'TAB_LAB_READ', edit: 'TAB_LAB_EDIT' },
+  { label: 'Patients', read: 'TAB_PATIENTS_READ', edit: 'TAB_PATIENTS_EDIT' },
+  { label: 'Appointment', read: 'TAB_APPOINTMENTS_READ', edit: 'TAB_APPOINTMENTS_EDIT' },
+  { label: 'Treatment', read: 'TAB_TREATMENT_READ', edit: 'TAB_TREATMENT_EDIT' },
+  { label: 'Billing', read: 'TAB_BILLING_READ', edit: 'TAB_BILLING_EDIT' },
+  { label: 'Reports', read: 'TAB_REPORTS_READ', edit: 'TAB_REPORTS_EDIT' },
+] as const;
+
+/** Map EDIT key -> { read, edit } for checkbox grid */
+export type FeaturePermState = Record<string, { read: boolean; edit: boolean }>;
+
+export function emptyFeaturePermissionState(): FeaturePermState {
+  const s: FeaturePermState = {};
+  for (const g of STAFF_FEATURE_GROUPS) {
+    s[g.edit] = { read: false, edit: false };
+  }
+  return s;
+}
+
+export function featureStateFromPermissionNames(names: string[]): FeaturePermState {
+  const set = new Set(names);
+  const s = emptyFeaturePermissionState();
+  for (const g of STAFF_FEATURE_GROUPS) {
+    const hasEdit = set.has(g.edit);
+    const hasRead = set.has(g.read) || hasEdit;
+    s[g.edit] = { read: hasRead, edit: hasEdit };
+  }
+  return s;
+}
+
+export function permissionNamesFromFeatureState(state: FeaturePermState): string[] {
+  const out: string[] = [];
+  for (const g of STAFF_FEATURE_GROUPS) {
+    const cell = state[g.edit];
+    if (!cell) continue;
+    if (cell.edit) out.push(g.edit);
+    else if (cell.read) out.push(g.read);
+  }
+  return out;
+}

frontend/src/app/(dashboard)/staff/page.tsx

@@ -0,0 +1,630 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useRouter } from 'next/navigation';
+import {
+  firstAccessibleDashboardPath,
+  canEditStaff,
+  canViewStaff,
+} from '@/shared/permissions';
+import {
+  STAFF_FEATURE_GROUPS,
+  permissionNamesFromFeatureState,
+  emptyFeaturePermissionState,
+  featureStateFromPermissionNames,
+  resolveStaffFeatureLabel,
+  formatAccessSummary,
+  type FeaturePermState,
+} from './staff-permission-form';
+import { UserPlus, Pencil, Trash2, Copy, Check, X, Clock3 } from 'lucide-react';
+import { useAuth } from '@/lib/hooks/useAuth';
+import { staffApi, type StaffMemberDto } from '@/lib/api/staff';
+import { Button } from '@/components/ui/common/Button';
+import { Input } from '@/components/ui/common/Input';
+import { Checkbox } from '@/components/ui/common/Checkbox';
+import type { ApiError } from '@/types/api';
+
+type StoredInviteLink = {
+  membershipId: string;
+  email: string;
+  invitationUrl: string;
+};
+
+function inviteLinksStorageKey(orgId: string): string {
+  return `staffInviteLinks:${orgId}`;
+}
+
+function readStoredInviteLinks(orgId: string): Record<string, StoredInviteLink> {
+  if (typeof window === 'undefined') return {};
+  try {
+    const raw = window.localStorage.getItem(inviteLinksStorageKey(orgId));
+    if (!raw) return {};
+    const parsed = JSON.parse(raw) as Record<string, StoredInviteLink>;
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeStoredInviteLinks(orgId: string, links: Record<string, StoredInviteLink>) {
+  if (typeof window === 'undefined') return;
+  window.localStorage.setItem(inviteLinksStorageKey(orgId), JSON.stringify(links));
+}
+
+function formatApiMessage(err: unknown): string {
+  if (!err || typeof err !== 'object') return 'Something went wrong';
+  const m = (err as ApiError).message;
+  if (Array.isArray(m)) return m.join(', ');
+  if (typeof m === 'string') return m;
+  return 'Something went wrong';
+}
+
+function PermissionGrid({
+  state,
+  onChange,
+  disabled,
+  organizationType,
+}: {
+  state: FeaturePermState;
+  onChange: (next: FeaturePermState) => void;
+  disabled?: boolean;
+  organizationType?: 'CLINIC' | 'LAB';
+}) {
+  const setRead = (editKey: string, read: boolean) => {
+    const cur = state[editKey] ?? { read: false, edit: false };
+    onChange({
+      ...state,
+      [editKey]: { read, edit: read ? cur.edit : false },
+    });
+  };
+
+  const setEdit = (editKey: string, edit: boolean) => {
+    const cur = state[editKey] ?? { read: false, edit: false };
+    onChange({
+      ...state,
+      [editKey]: { read: edit || cur.read, edit },
+    });
+  };
+
+  return (
+    <div className="grid gap-3 sm:grid-cols-2">
+      {STAFF_FEATURE_GROUPS.map((g) => {
+        const cell = state[g.edit] ?? { read: false, edit: false };
+        return (
+          <div
+            key={g.edit}
+            className="flex flex-col gap-3 rounded-[var(--radius-md)] border border-border/60 bg-background-card/50 px-3 py-3"
+          >
+            <span className="text-sm font-medium text-text-primary">
+              {resolveStaffFeatureLabel(g, organizationType)}
+            </span>
+            <div className="flex flex-col gap-2.5 pl-0.5">
+              <Checkbox
+                checked={cell.read}
+                disabled={disabled}
+                label="View"
+                onChange={(v) => setRead(g.edit, v)}
+              />
+              <Checkbox
+                checked={cell.edit}
+                disabled={disabled}
+                label="Edit"
+                onChange={(v) => setEdit(g.edit, v)}
+              />
+            </div>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+export default function StaffPage() {
+  const router = useRouter();
+  const { currentOrganization, user } = useAuth();
+  const [members, setMembers] = useState<StaffMemberDto[]>([]);
+  const [seats, setSeats] = useState<{
+    used: number;
+    limit: number | null;
+    unlimited: boolean;
+  } | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState('');
+  const [success, setSuccess] = useState('');
+
+  const [inviteOpen, setInviteOpen] = useState(false);
+  const [inviteEmail, setInviteEmail] = useState('');
+  const [inviteName, setInviteName] = useState('');
+  const [invitePerms, setInvitePerms] = useState(() => emptyFeaturePermissionState());
+  const [inviteLoading, setInviteLoading] = useState(false);
+  const [copiedInviteMembershipId, setCopiedInviteMembershipId] = useState<string | null>(null);
+  const [lastInviteInfo, setLastInviteInfo] = useState<{
+    membershipId: string;
+    name: string;
+    email: string;
+    invitationUrl: string | null;
+    invitationStatus: 'PENDING' | 'ACCEPTED';
+  } | null>(null);
+  const [pendingInviteLinks, setPendingInviteLinks] = useState<Record<string, StoredInviteLink>>({});
+
+  const [editing, setEditing] = useState<StaffMemberDto | null>(null);
+  const [editName, setEditName] = useState('');
+  const [editPerms, setEditPerms] = useState(() => emptyFeaturePermissionState());
+  const [editLoading, setEditLoading] = useState(false);
+
+  const canEdit = useMemo(() => canEditStaff(currentOrganization), [currentOrganization]);
+  const hasActivePlan = Boolean(currentOrganization?.plan);
+  const atSeatLimit = useMemo(() => {
+    if (!seats || seats.unlimited) return false;
+    if (seats.limit == null) return false;
+    return seats.used >= seats.limit;
+  }, [seats]);
+
+  const load = useCallback(async () => {
+    setError('');
+    setLoading(true);
+    try {
+      const res = await staffApi.list();
+      setMembers(res.data.members);
+      setSeats(res.data.seats);
+    } catch (e) {
+      setError(formatApiMessage(e));
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!currentOrganization?.id) return;
+    setPendingInviteLinks(readStoredInviteLinks(currentOrganization.id));
+  }, [currentOrganization?.id]);
+
+  useEffect(() => {
+    if (!currentOrganization?.id || loading) return;
+
+    const activeMemberIds = new Set(
+      members
+        .filter((m) => m.isOwner || m.invitationStatus === 'ACTIVE')
+        .map((m) => m.id),
+    );
+
+    let changed = false;
+    const nextLinks: Record<string, StoredInviteLink> = { ...pendingInviteLinks };
+    for (const memberId of Object.keys(nextLinks)) {
+      if (activeMemberIds.has(memberId)) {
+        delete nextLinks[memberId];
+        changed = true;
+      }
+    }
+    if (!changed) return;
+
+    setPendingInviteLinks(nextLinks);
+    writeStoredInviteLinks(currentOrganization.id, nextLinks);
+  }, [currentOrganization?.id, loading, members, pendingInviteLinks]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  useEffect(() => {
+    if (!currentOrganization) return;
+    if (!canViewStaff(currentOrganization)) {
+      router.replace(firstAccessibleDashboardPath(currentOrganization));
+    }
+  }, [currentOrganization, router]);
+
+  useEffect(() => {
+    if (!success) return;
+    const t = setTimeout(() => setSuccess(''), 4000);
+    return () => clearTimeout(t);
+  }, [success]);
+
+  async function submitInvite() {
+    setInviteLoading(true);
+    setError('');
+    setLastInviteInfo(null);
+    const displayName = inviteName.trim();
+    const displayEmail = inviteEmail.trim();
+    try {
+      const permissionNames = permissionNamesFromFeatureState(invitePerms);
+      const res = await staffApi.invite({
+        email: displayEmail,
+        name: displayName,
+        permissionNames,
+      });
+      setLastInviteInfo({
+        membershipId: res.data.membershipId,
+        name: displayName,
+        email: res.data.email,
+        invitationUrl: res.data.invitationUrl,
+        invitationStatus: res.data.invitationStatus,
+      });
+      if (currentOrganization?.id && res.data.invitationUrl) {
+        const nextLinks = {
+          ...pendingInviteLinks,
+          [res.data.membershipId]: {
+            membershipId: res.data.membershipId,
+            email: res.data.email,
+            invitationUrl: res.data.invitationUrl,
+          },
+        };
+        setPendingInviteLinks(nextLinks);
+        writeStoredInviteLinks(currentOrganization.id, nextLinks);
+      }
+      setSuccess('');
+      setInviteOpen(false);
+      setInviteEmail('');
+      setInviteName('');
+      setInvitePerms(emptyFeaturePermissionState());
+      await load();
+    } catch (e) {
+      setError(formatApiMessage(e));
+    } finally {
+      setInviteLoading(false);
+    }
+  }
+
+  function openEdit(m: StaffMemberDto) {
+    if (m.isOwner) return;
+    setEditing(m);
+    setEditName(m.name);
+    setEditPerms(
+      featureStateFromPermissionNames(m.permissions ?? []),
+    );
+  }
+
+  async function submitEdit() {
+    if (!editing) return;
+    setEditLoading(true);
+    setError('');
+    try {
+      await staffApi.updateMember(editing.id, {
+        name: editName.trim(),
+        permissionNames: permissionNamesFromFeatureState(editPerms),
+      });
+      setSuccess('Member updated');
+      setEditing(null);
+      await load();
+    } catch (e) {
+      setError(formatApiMessage(e));
+    } finally {
+      setEditLoading(false);
+    }
+  }
+
+  async function removeMember(m: StaffMemberDto) {
+    if (m.isOwner) return;
+    if (m.userId === user?.id) {
+      if (!confirm('Remove yourself from this organization? You will lose access.')) return;
+    } else {
+      if (!confirm(`Remove ${m.name} from this organization?`)) return;
+    }
+    setError('');
+    try {
+      await staffApi.removeMember(m.id);
+      setSuccess('Member removed');
+      await load();
+    } catch (e) {
+      setError(formatApiMessage(e));
+    }
+  }
+
+  if (!currentOrganization || !canViewStaff(currentOrganization)) {
+    return (
+      <p className="text-sm text-text-secondary">Redirecting…</p>
+    );
+  }
+
+  return (
+    <div className="space-y-6">
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+        <div>
+          <h1 className="text-2xl font-semibold text-text-primary">Staff Management</h1>
+          <p className="text-sm text-text-secondary mt-1">
+            Invite teammates, set tab access, and stay within your plan seat limit.
+          </p>
+        </div>
+        <Button
+          size="sm"
+          onClick={() => {
+            if (!canEdit || atSeatLimit) return;
+            setInviteOpen(true);
+            setLastInviteInfo(null);
+          }}
+          disabled={!canEdit || atSeatLimit}
+          className="shrink-0"
+          title={!canEdit ? 'Read-only access for this organization.' : undefined}
+        >
+          <UserPlus className="w-4 h-4 mr-2" />
+          Invite member
+        </Button>
+      </div>
+
+      {seats && (
+        <p className="text-sm text-text-secondary">
+          Seats:{' '}
+          <span className="text-text-primary font-medium">
+            {seats.used}
+            {seats.unlimited ? ' (unlimited plan)' : ` / ${seats.limit}`}
+          </span>
+          {!seats.unlimited && atSeatLimit && (
+            <span className="text-amber-600 dark:text-amber-400 ml-2">
+              {hasActivePlan
+                ? 'Plan seat limit reached for this organization.'
+                : 'No active plan selected for this organization. Choose a subscription plan to invite members.'}
+            </span>
+          )}
+        </p>
+      )}
+
+      {error && (
+        <div className="rounded-[var(--radius-md)] border border-red-500/40 bg-red-500/10 px-4 py-3 text-sm text-red-700 dark:text-red-300">
+          {error}
+        </div>
+      )}
+
+      {success && (
+        <div className="rounded-[var(--radius-md)] border border-primary/30 bg-primary-soft/40 px-4 py-3 text-sm text-text-primary">
+          {success}
+        </div>
+      )}
+
+      {lastInviteInfo && (
+        <div className="relative rounded-[var(--radius-md)] border border-border-strong bg-background-secondary/90 px-4 py-3 pr-12 shadow-[inset_0_1px_0_rgba(255,255,255,0.04)] space-y-3">
+          <button
+            type="button"
+            className="absolute right-2 top-2 p-1.5 rounded-[var(--radius-sm)] text-text-muted hover:text-text-primary hover:bg-background-card/80"
+            aria-label="Dismiss"
+            onClick={() => {
+              setLastInviteInfo(null);
+            }}
+          >
+            <X className="w-4 h-4" />
+          </button>
+          <p className="text-sm text-text-primary pr-6">
+            <span className="font-medium">{lastInviteInfo.name}</span> ({lastInviteInfo.email}) was invited.
+            {lastInviteInfo.invitationStatus === 'PENDING'
+              ? ' Invitation is pending until they open the link, set a password, and log in.'
+              : ' Invitation was accepted immediately.'}
+          </p>
+          {lastInviteInfo.invitationUrl && (
+            <div className="space-y-2 pt-1 border-t border-border/60">
+              <p className="text-xs font-medium text-text-secondary uppercase tracking-wide">
+                Invite link
+              </p>
+              <div className="flex flex-wrap items-center gap-2">
+                <code className="text-sm px-2 py-1.5 rounded-[var(--radius-sm)] bg-background-card border border-border font-mono break-all">
+                  {lastInviteInfo.invitationUrl}
+                </code>
+                <Button
+                  type="button"
+                  variant="outline"
+                  size="sm"
+                  onClick={async () => {
+                    try {
+                      await navigator.clipboard.writeText(lastInviteInfo.invitationUrl as string);
+                      setCopiedInviteMembershipId(lastInviteInfo.membershipId);
+                      setTimeout(() => setCopiedInviteMembershipId(null), 1500);
+                    } catch {
+                      setError('Could not copy invitation link');
+                    }
+                  }}
+                >
+                  {copiedInviteMembershipId === lastInviteInfo.membershipId ? (
+                    <Check className="w-4 h-4" />
+                  ) : (
+                    <Copy className="w-4 h-4" />
+                  )}
+                  <span className="ml-1">
+                    {copiedInviteMembershipId === lastInviteInfo.membershipId ? 'Copied' : 'Copy link'}
+                  </span>
+                </Button>
+              </div>
+              <p className="text-xs text-text-muted">
+                Share this link manually via SMS or email. They must set password first.
+              </p>
+            </div>
+          )}
+        </div>
+      )}
+
+      {loading ? (
+        <p className="text-sm text-text-secondary">Loading team…</p>
+      ) : (
+        <div className="overflow-x-auto rounded-[var(--radius-md)] border border-border/70">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="border-b border-border/70 text-left text-text-secondary">
+                <th className="p-3 font-medium">Name</th>
+                <th className="p-3 font-medium">Email</th>
+                <th className="p-3 font-medium">Role</th>
+                <th className="p-3 font-medium">Status</th>
+                <th className="p-3 font-medium">Access</th>
+                <th className="p-3 font-medium w-28">Actions</th>
+              </tr>
+            </thead>
+            <tbody>
+              {members.map((m) => (
+                <tr key={m.id} className="h-14 border-b border-border/40 last:border-0">
+                  <td className="p-3 text-text-primary">{m.name}</td>
+                  <td className="p-3 text-text-secondary">{m.email}</td>
+                  <td className="p-3">
+                    {m.isOwner ? (
+                      <span className="text-primary font-medium">Owner</span>
+                    ) : (
+                      <span className="text-text-secondary">Staff</span>
+                    )}
+                  </td>
+                  <td className="p-3 align-middle">
+                    {m.isOwner || m.invitationStatus === 'ACTIVE' ? (
+                      <span className="inline-flex items-center rounded-full border border-emerald-600/40 bg-emerald-600/15 px-2 py-0.5 text-xs text-emerald-400">
+                        Active
+                      </span>
+                    ) : m.invitationStatus === 'PENDING' ? (
+                      <span className="inline-flex items-center gap-1 rounded-full border border-amber-500/40 bg-amber-500/15 px-2 py-0.5 text-xs text-amber-300">
+                        <Clock3 className="h-3 w-3" />
+                        Pending
+                      </span>
+                    ) : (
+                      <span className="inline-flex items-center rounded-full border border-red-500/40 bg-red-500/15 px-2 py-0.5 text-xs text-red-300">
+                        Expired
+                      </span>
+                    )}
+                  </td>
+                  <td className="p-3 text-text-secondary max-w-md">
+                    {m.isOwner ? (
+                      <span className="text-text-muted">All features</span>
+                    ) : (
+                      <span className="line-clamp-3 text-sm leading-relaxed">
+                        {formatAccessSummary(m.permissions, currentOrganization?.type)}
+                      </span>
+                    )}
+                  </td>
+                  <td className="p-3 align-middle">
+                    {!m.isOwner && (
+                      <div className="flex min-h-[36px] items-center justify-end gap-1">
+                        {m.invitationStatus === 'PENDING' && pendingInviteLinks[m.id]?.invitationUrl && (
+                          <button
+                            type="button"
+                            className="p-2 rounded-md text-text-secondary hover:bg-background-card/80 hover:text-text-primary"
+                            onClick={async () => {
+                              try {
+                                await navigator.clipboard.writeText(pendingInviteLinks[m.id].invitationUrl);
+                                setCopiedInviteMembershipId(m.id);
+                                setTimeout(() => setCopiedInviteMembershipId(null), 1500);
+                              } catch {
+                                setError('Could not copy invitation link');
+                              }
+                            }}
+                            aria-label="Copy invite link"
+                            title="Copy invite link"
+                          >
+                            {copiedInviteMembershipId === m.id ? (
+                              <Check className="w-4 h-4" />
+                            ) : (
+                              <Copy className="w-4 h-4" />
+                            )}
+                          </button>
+                        )}
+                        <button
+                          type="button"
+                          className={`p-2 rounded-md ${
+                            canEdit
+                              ? 'text-text-secondary hover:bg-background-card/80 hover:text-text-primary'
+                              : 'text-text-muted opacity-50 cursor-not-allowed'
+                          }`}
+                          aria-label="Edit member"
+                          disabled={!canEdit}
+                          onClick={() => {
+                            if (!canEdit) return;
+                            openEdit(m);
+                          }}
+                        >
+                          <Pencil className="w-4 h-4" />
+                        </button>
+                        <button
+                          type="button"
+                          className={`p-2 rounded-md ${
+                            canEdit
+                              ? 'text-text-secondary hover:bg-red-500/15 hover:text-red-600'
+                              : 'text-text-muted opacity-50 cursor-not-allowed'
+                          }`}
+                          aria-label="Remove member"
+                          disabled={!canEdit}
+                          onClick={() => {
+                            if (!canEdit) return;
+                            void removeMember(m);
+                          }}
+                        >
+                          <Trash2 className="w-4 h-4" />
+                        </button>
+                      </div>
+                    )}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+
+      {inviteOpen && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center p-4 bg-black/50">
+          <div
+            className="w-full max-w-lg max-h-[90vh] overflow-y-auto rounded-[var(--radius-md)] border border-border bg-background-secondary p-6 shadow-xl space-y-4"
+            role="dialog"
+            aria-modal="true"
+            aria-labelledby="invite-staff-title"
+          >
+            <h2 id="invite-staff-title" className="text-lg font-semibold text-text-primary">
+              Invite team member
+            </h2>
+            <Input
+              label="Email"
+              type="email"
+              value={inviteEmail}
+              onChange={(e) => setInviteEmail(e.target.value)}
+              autoComplete="off"
+            />
+            <Input
+              label="Display name"
+              value={inviteName}
+              onChange={(e) => setInviteName(e.target.value)}
+            />
+            <div>
+              <p className="text-sm font-medium text-text-secondary mb-2">Tab access</p>
+              <PermissionGrid
+                state={invitePerms}
+                onChange={setInvitePerms}
+                organizationType={currentOrganization?.type}
+              />
+            </div>
+            <div className="flex justify-end gap-2 pt-2">
+              <Button variant="outline" type="button" onClick={() => setInviteOpen(false)}>
+                Cancel
+              </Button>
+              <Button
+                type="button"
+                isLoading={inviteLoading}
+                disabled={!inviteEmail.trim() || !inviteName.trim()}
+                onClick={() => void submitInvite()}
+              >
+                Send invite
+              </Button>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {editing && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center p-4 bg-black/50">
+          <div
+            className="w-full max-w-lg max-h-[90vh] overflow-y-auto rounded-[var(--radius-md)] border border-border bg-background-secondary p-6 shadow-xl space-y-4"
+            role="dialog"
+            aria-modal="true"
+          >
+            <h2 className="text-lg font-semibold text-text-primary">Edit member</h2>
+            <p className="text-xs text-text-muted">{editing.email}</p>
+            <Input label="Display name" value={editName} onChange={(e) => setEditName(e.target.value)} />
+            <div>
+              <p className="text-sm font-medium text-text-secondary mb-2">Tab access</p>
+              <PermissionGrid
+                state={editPerms}
+                onChange={setEditPerms}
+                organizationType={currentOrganization?.type}
+              />
+            </div>
+            <div className="flex justify-end gap-2 pt-2">
+              <Button variant="outline" type="button" onClick={() => setEditing(null)}>
+                Cancel
+              </Button>
+              <Button type="button" isLoading={editLoading} onClick={() => void submitEdit()}>
+                Save
+              </Button>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/app/(dashboard)/staff/staff-permission-form.ts

@@ -0,0 +1,76 @@
+/**
+ * Staff route only: tab matrix + checkbox state ↔ TAB_* permission names.
+ * Add presentational pieces under ./components/ as the UI grows.
+ */
+
+export const STAFF_FEATURE_GROUPS = [
+  { label: 'Today', read: 'TAB_TODAY_READ', edit: 'TAB_TODAY_EDIT' },
+  { label: 'Staff', read: 'TAB_STAFF_READ', edit: 'TAB_STAFF_EDIT' },
+  { label: 'Labs', read: 'TAB_LAB_READ', edit: 'TAB_LAB_EDIT' },
+  { label: 'Patients', read: 'TAB_PATIENTS_READ', edit: 'TAB_PATIENTS_EDIT' },
+  { label: 'Appointment', read: 'TAB_APPOINTMENTS_READ', edit: 'TAB_APPOINTMENTS_EDIT' },
+  { label: 'Treatment', read: 'TAB_TREATMENT_READ', edit: 'TAB_TREATMENT_EDIT' },
+  { label: 'Billing', read: 'TAB_BILLING_READ', edit: 'TAB_BILLING_EDIT' },
+  { label: 'Reports', read: 'TAB_REPORTS_READ', edit: 'TAB_REPORTS_EDIT' },
+] as const;
+
+export type FeaturePermState = Record<string, { read: boolean; edit: boolean }>;
+export type OrgType = 'CLINIC' | 'LAB' | null | undefined;
+
+export function resolveStaffFeatureLabel(
+  group: (typeof STAFF_FEATURE_GROUPS)[number],
+  organizationType: OrgType,
+): string {
+  if (group.read === 'TAB_LAB_READ') {
+    return organizationType === 'LAB' ? 'Clinics' : 'Labs';
+  }
+  return group.label;
+}
+
+export function emptyFeaturePermissionState(): FeaturePermState {
+  const s: FeaturePermState = {};
+  for (const g of STAFF_FEATURE_GROUPS) {
+    s[g.edit] = { read: false, edit: false };
+  }
+  return s;
+}
+
+export function featureStateFromPermissionNames(names: string[]): FeaturePermState {
+  const set = new Set(names);
+  const s = emptyFeaturePermissionState();
+  for (const g of STAFF_FEATURE_GROUPS) {
+    const hasEdit = set.has(g.edit);
+    const hasRead = set.has(g.read) || hasEdit;
+    s[g.edit] = { read: hasRead, edit: hasEdit };
+  }
+  return s;
+}
+
+export function permissionNamesFromFeatureState(state: FeaturePermState): string[] {
+  const out: string[] = [];
+  for (const g of STAFF_FEATURE_GROUPS) {
+    const cell = state[g.edit];
+    if (!cell) continue;
+    if (cell.edit) out.push(g.edit);
+    else if (cell.read) out.push(g.read);
+  }
+  return out;
+}
+
+/** Human-readable access for the team table — feature name, or "Feature (Read only)" */
+export function formatAccessSummary(
+  permissionNames: string[] | null | undefined,
+  organizationType?: OrgType,
+): string {
+  if (!permissionNames?.length) return 'No tab access';
+  const set = new Set(permissionNames);
+  const parts: string[] = [];
+  for (const g of STAFF_FEATURE_GROUPS) {
+    const hasEdit = set.has(g.edit);
+    const hasRead = set.has(g.read) || hasEdit;
+    if (!hasRead) continue;
+    const label = resolveStaffFeatureLabel(g, organizationType);
+    parts.push(hasEdit ? label : `${label} (Read only)`);
+  }
+  return parts.length ? parts.join(' · ') : 'No tab access';
+}

frontend/src/app/(dashboard)/today/page.tsx

@@ -1,10 +1,31 @@
+'use client';
+
+import Link from 'next/link';
+import { useAuth } from '@/lib/hooks/useAuth';
+
 export default function TodayPage() {
+  const { currentOrganization } = useAuth();
+  const showNoSubscriptionNotice =
+    Boolean(currentOrganization?.isOwner) && !currentOrganization?.plan;
+
   return (
     <div>
       <h1 className="text-2xl font-semibold mb-6">
         Welcome back Babak !!
       </h1>
 
+      {showNoSubscriptionNotice && (
+        <div className="mb-6 rounded-[var(--radius-md)] border border-amber-500/30 bg-amber-500/10 p-4">
+          <p className="text-sm text-amber-200">
+            This organization does not have an active subscription yet.{' '}
+            <Link href="/settings/subscriptions" className="font-medium underline underline-offset-2">
+              Choose a plan
+            </Link>{' '}
+            to start the purchase process.
+          </p>
+        </div>
+      )}
+
       <div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-4 gap-4">
         <Card title="Today's Appointments" value="12" sub="Monday 2/5/2026" />
         <Card title="Active Patients" value="675" />

frontend/src/app/(dashboard)/treatment/page.tsx

@@ -0,0 +1,10 @@
+export default function TreatmentPage() {
+  return (
+    <div className="space-y-3">
+      <h1 className="text-2xl font-semibold text-text-primary">Treatment</h1>
+      <p className="text-sm text-text-secondary">
+        Treatment module is coming soon.
+      </p>
+    </div>
+  );
+}

frontend/src/app/(public)/accept-invite/page.tsx

@@ -0,0 +1,166 @@
+'use client';
+
+import { useEffect, useMemo, useState } from 'react';
+import { Suspense } from 'react';
+import Link from 'next/link';
+import { useRouter, useSearchParams } from 'next/navigation';
+import { Button } from '@/components/ui/common/Button';
+import { Input } from '@/components/ui/common/Input';
+import { staffApi } from '@/lib/api/staff';
+
+function AcceptInviteContent() {
+  const params = useSearchParams();
+  const router = useRouter();
+  const token = useMemo(() => params.get('token') || '', [params]);
+
+  const [loading, setLoading] = useState(true);
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState('');
+  const [success, setSuccess] = useState('');
+  const [inviteInfo, setInviteInfo] = useState<{
+    email: string;
+    name: string;
+    organizationName: string;
+    expiresAt: string;
+    status: 'PENDING' | 'ACCEPTED';
+  } | null>(null);
+
+  const [name, setName] = useState('');
+  const [password, setPassword] = useState('');
+  const [confirmPassword, setConfirmPassword] = useState('');
+
+  useEffect(() => {
+    if (!token) {
+      setLoading(false);
+      setError('Invalid invitation link');
+      return;
+    }
+
+    void (async () => {
+      setLoading(true);
+      setError('');
+      try {
+        const res = await staffApi.previewInvite(token);
+        setInviteInfo(res.data);
+        setName(res.data.name || '');
+        if (res.data.status === 'ACCEPTED') {
+          setSuccess('This invitation is already accepted. You can log in now.');
+        }
+      } catch (e: any) {
+        setError(e?.message || 'Could not load invitation');
+      } finally {
+        setLoading(false);
+      }
+    })();
+  }, [token]);
+
+  async function onAccept() {
+    if (!token) return;
+    setError('');
+    setSuccess('');
+    if (!name.trim()) {
+      setError('Name is required');
+      return;
+    }
+    if (password.length < 8) {
+      setError('Password must be at least 8 characters');
+      return;
+    }
+    if (password !== confirmPassword) {
+      setError('Passwords do not match');
+      return;
+    }
+
+    setSubmitting(true);
+    try {
+      await staffApi.acceptInvite({
+        token,
+        name: name.trim(),
+        password,
+      });
+      setSuccess('Invitation accepted. Redirecting to login...');
+      setTimeout(() => {
+        router.replace('/login');
+      }, 1000);
+    } catch (e: any) {
+      setError(e?.message || 'Could not accept invitation');
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  return (
+    <div className="min-h-screen app-web-bg flex items-center justify-center p-4">
+      <div className="w-full max-w-md surface-card p-6 space-y-5">
+        <h1 className="text-xl font-semibold text-text-primary">Accept invitation</h1>
+
+        {loading ? (
+          <p className="text-sm text-text-secondary">Loading invitation...</p>
+        ) : (
+          <>
+            {inviteInfo && (
+              <div className="rounded-[var(--radius-md)] border border-border/70 bg-background-secondary/70 px-3 py-2 text-sm text-text-secondary space-y-1">
+                <p>
+                  Organization: <span className="text-text-primary">{inviteInfo.organizationName}</span>
+                </p>
+                <p>
+                  Email: <span className="text-text-primary">{inviteInfo.email}</span>
+                </p>
+              </div>
+            )}
+
+            {error && (
+              <div className="rounded-[var(--radius-md)] border border-red-500/40 bg-red-500/10 px-3 py-2 text-sm text-red-300">
+                {error}
+              </div>
+            )}
+            {success && (
+              <div className="rounded-[var(--radius-md)] border border-primary/30 bg-primary-soft/40 px-3 py-2 text-sm text-text-primary">
+                {success}
+              </div>
+            )}
+
+            {inviteInfo?.status !== 'ACCEPTED' && (
+              <div className="space-y-3">
+                <Input label="Name" value={name} onChange={(e) => setName(e.target.value)} />
+                <Input
+                  label="Create password"
+                  type="password"
+                  value={password}
+                  onChange={(e) => setPassword(e.target.value)}
+                />
+                <Input
+                  label="Confirm password"
+                  type="password"
+                  value={confirmPassword}
+                  onChange={(e) => setConfirmPassword(e.target.value)}
+                />
+                <Button type="button" fullWidth isLoading={submitting} onClick={() => void onAccept()}>
+                  Activate account
+                </Button>
+              </div>
+            )}
+
+            <p className="text-xs text-text-muted">
+              Already have access? <Link href="/login" className="text-primary">Go to login</Link>
+            </p>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export default function AcceptInvitePage() {
+  return (
+    <Suspense
+      fallback={
+        <div className="min-h-screen app-web-bg flex items-center justify-center">
+          <p className="text-sm text-text-secondary">Loading invitation...</p>
+        </div>
+      }
+    >
+      <AcceptInviteContent />
+    </Suspense>
+  );
+}

frontend/src/app/(public)/login/page.tsx

@@ -116,8 +116,8 @@ import Link from 'next/link';
 import { Mail, Lock } from 'lucide-react';
 
 import { useAuth } from '@/lib/hooks/useAuth';
-import { Button } from '@/components/ui/Button';
-import { Input } from '@/components/ui/Input';
+import { Button } from '@/components/ui/common/Button';
+import { Input } from '@/components/ui/common/Input';
 
 const loginSchema = z.object({
   email: z.string().email('Please enter a valid email address'),

frontend/src/app/(public)/page.tsx

@@ -2,8 +2,8 @@
 
 import Link from 'next/link';
 import { useAuth } from '@/lib/hooks/useAuth';
-import { Button } from '@/components/ui/Button';
-import { ThemeToggle } from '@/components/ui/ThemeToggle';
+import { Button } from '@/components/ui/common/Button';
+import { ThemeToggle } from '@/components/ui/common/ThemeToggle';
 import { Building2, Beaker, Calendar, Shield, Clock, Users } from 'lucide-react';
 
 export default function HomePage() {

frontend/src/app/(public)/register/page.tsx

@@ -7,8 +7,8 @@ import * as z from 'zod';
 import Link from 'next/link';
 import { Building2, Mail, Lock, User, ChevronRight } from 'lucide-react';
 import { useAuth } from '@/lib/hooks/useAuth';
-import { Button } from '@/components/ui/Button';
-import { Input } from '@/components/ui/Input';
+import { Button } from '@/components/ui/common/Button';
+import { Input } from '@/components/ui/common/Input';
 const registerSchema = z.object({
     name: z.string().min(2, 'Name must be at least 2 characters'),
     email: z.string().email('Please enter a valid email address'),
@@ -18,6 +18,7 @@ const registerSchema = z.object({
         .regex(/[0-9]/, 'Password must contain at least one number'),
     confirmPassword: z.string(),
     organizationName: z.string().min(2, 'Organization name must be at least 2 characters'),
+    organizationEmail: z.string().email('Please enter a valid organization email'),
     organizationType: z.enum(['CLINIC', 'LAB'], {
         message: 'Please select organization type',
     }),
@@ -47,7 +48,7 @@ export default function RegisterPage() {
     const handleNext = async () => {
         const fieldsToValidate = step === 1
             ? ['name', 'email', 'password', 'confirmPassword']
-            : ['organizationName', 'organizationType'];
+            : ['organizationName', 'organizationEmail', 'organizationType'];
 
         const isValid = await trigger(fieldsToValidate as any);
         if (isValid) {
@@ -62,6 +63,7 @@ export default function RegisterPage() {
                 data.password,
                 data.name,
                 data.organizationName,
+                data.organizationEmail,
                 data.organizationType
             );
             // No need to redirect - auth context will handle it
@@ -182,6 +184,14 @@ export default function RegisterPage() {
                                     error={errors.organizationName?.message}
                                     icon={<Building2 className="h-5 w-5 icon-flat" />}
                                 />
+                                <Input
+                                    label="Organization email"
+                                    {...register('organizationEmail')}
+                                    type="email"
+                                    placeholder="contact@sunshineclinic.com"
+                                    error={errors.organizationEmail?.message}
+                                    icon={<Mail className="h-5 w-5 icon-flat" />}
+                                />
                                 <div>
                                     <label className="block text-sm font-medium text-text-secondary mb-2">
                                         Organization type

frontend/src/app/(public)/select-organization/page.tsx

@@ -1,79 +1,12 @@
 'use client';
 
-import { useEffect } from 'react';
-import { useAuth } from '@/lib/hooks/useAuth';
-import { Building2, Beaker } from 'lucide-react';
+import { OrganizationSelectorContent } from '@/components/ui/organization/OrganizationSelectorContent';
 
 export default function SelectOrganizationPage() {
-  const { organizations, selectOrganization, isLoading } = useAuth();
-
-  // ✅ Auto-redirect if only one organization
-  useEffect(() => {
-    if (!isLoading && organizations.length === 1) {
-      selectOrganization(organizations[0].id);
-    }
-  }, [organizations, isLoading]);
-
-  const getIcon = (type: string) => {
-    return type === 'CLINIC'
-      ? <Building2 className="h-8 w-8 icon-flat" />
-      : <Beaker className="h-8 w-8 icon-flat" />;
-  };
-
-  if (isLoading) {
-    return (
-      <div className="min-h-screen app-web-bg flex items-center justify-center">
-        <p className="text-text-secondary">Loading organizations...</p>
-      </div>
-    );
-  }
-
-  if (!organizations.length) {
-    return (
-      <div className="min-h-screen app-web-bg flex items-center justify-center">
-        <p className="text-text-secondary">No organizations found.</p>
-      </div>
-    );
-  }
-
   return (
-    <div className="min-h-screen app-web-bg flex items-center justify-center p-4">
-      <div className="max-w-2xl w-full">
-        <div className="text-center mb-8">
-          <h1 className="text-3xl font-semibold text-text-primary">
-            Choose Organization
-          </h1>
-          <p className="text-text-secondary mt-2">
-            You have access to multiple organizations. Select one to continue.
-          </p>
-        </div>
-
-        <div className="grid gap-4">
-          {organizations.map((org) => (
-            <button
-              key={org.id}
-              onClick={() => selectOrganization(org.id)}
-              className="surface-card p-6 transition-all text-left flex items-center gap-4 hover:border-primary/60"
-            >
-              <div className="p-3 bg-primary-soft rounded-[var(--radius-sm)] text-primary">
-                {getIcon(org.type)}
-              </div>
-
-              <div className="flex-1">
-                <h3 className="text-lg font-semibold text-text-primary">
-                  {org.name}
-                </h3>
-                <p className="text-sm text-text-secondary">
-                  {org.type === 'CLINIC' ? 'Dental Clinic' : 'Dental Lab'}
-                </p>
-              </div>
-
-              <div className="text-primary text-sm">
-                Continue →
-              </div>
-            </button>
-          ))}
-        </div>
+    <div className="min-h-screen app-web-bg p-4 sm:p-8">
+      <div className="max-w-3xl mx-auto">
+        <OrganizationSelectorContent />
       </div>
     </div>
   );

frontend/src/components/ui/Sidebar.tsx

@@ -1,57 +0,0 @@
-'use client';
-
-import { usePathname, useRouter } from 'next/navigation';
-import {
-  LayoutDashboard,
-  Users,
-  Calendar,
-  UserCog,
-  FlaskConical,
-  FileText,
-  CreditCard
-} from 'lucide-react';
-
-const menu = [
-  { name: 'Today', path: '/today', icon: LayoutDashboard },
-  { name: 'Patients', path: '/patients', icon: Users },
-  { name: 'Appointments', path: '/appointments', icon: Calendar },
-  { name: 'Staff Management', path: '/staff', icon: UserCog },
-  { name: 'Lab Management', path: '/lab', icon: FlaskConical },
-  { name: 'Billing', path: '/billing', icon: CreditCard },
-  { name: 'Reports', path: '/reports', icon: FileText },
-];
-
-export default function Sidebar() {
-  const pathname = usePathname();
-  const router = useRouter();
-
-  return (
-    <aside className="w-64 bg-background-secondary/90 border-r border-border text-text-primary flex flex-col p-4">
-      <div className="mb-6 pb-4 border-b border-border">
-        <h1 className="text-xl font-semibold tracking-tight">DyoLink</h1>
-      </div>
-
-      <nav className="flex flex-col gap-2">
-        {menu.map((item) => {
-          const Icon = item.icon;
-          const isActive = pathname === item.path;
-
-          return (
-            <button
-              key={item.name}
-              onClick={() => router.push(item.path)}
-              className={`flex items-center gap-3 px-3 py-2.5 rounded-[var(--radius-sm)] border transition-colors ${
-                isActive
-                  ? 'bg-primary-soft border-primary/60 text-text-primary'
-                  : 'border-border/50 text-text-secondary hover:bg-background-card/70 hover:text-text-primary hover:border-border'
-              }`}
-            >
-              <Icon className="w-[18px] h-[18px] icon-flat" />
-              <span className="text-sm">{item.name}</span>
-            </button>
-          );
-        })}
-      </nav>
-    </aside>
-  );
-}

frontend/src/components/ui/common/Checkbox.tsx

@@ -0,0 +1,70 @@
+'use client';
+
+import { useId } from 'react';
+import { Check } from 'lucide-react';
+
+type CheckboxProps = {
+  checked: boolean;
+  onChange: (checked: boolean) => void;
+  disabled?: boolean;
+  label: string;
+  id?: string;
+  className?: string;
+};
+
+/**
+ * App design-system checkbox: primary fill when checked, rounded, focus-visible ring.
+ */
+export function Checkbox({
+  checked,
+  onChange,
+  disabled = false,
+  label,
+  id,
+  className = '',
+}: CheckboxProps) {
+  const genId = useId();
+  const inputId = id ?? genId;
+
+  return (
+    <label
+      htmlFor={inputId}
+      className={`
+        inline-flex items-center gap-2.5 cursor-pointer select-none rounded-[var(--radius-sm)] -m-0.5 p-0.5
+        has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-primary/45 has-[:focus-visible]:ring-offset-2
+        has-[:focus-visible]:ring-offset-background-secondary
+        ${disabled ? 'opacity-50 cursor-not-allowed' : ''}
+        ${className}
+      `}
+    >
+      <input
+        id={inputId}
+        type="checkbox"
+        className="sr-only"
+        checked={checked}
+        disabled={disabled}
+        onChange={(e) => onChange(e.target.checked)}
+      />
+      <span
+        className={`
+          flex h-5 w-5 shrink-0 items-center justify-center rounded-[var(--radius-sm)] border-2 transition-all duration-200
+          shadow-[inset_0_1px_0_rgba(255,255,255,0.05)]
+          ${
+            checked
+              ? 'border-primary bg-primary shadow-[0_0_0_1px_rgba(9,169,188,0.25)]'
+              : 'border-border-strong bg-background-card/90 hover:border-border'
+          }
+        `}
+        aria-hidden
+      >
+        <Check
+          strokeWidth={3}
+          className={`h-3.5 w-3.5 text-primary-contrast transition-all duration-200 ${
+            checked ? 'scale-100 opacity-100' : 'scale-75 opacity-0'
+          }`}
+        />
+      </span>
+      <span className="text-sm text-text-secondary">{label}</span>
+    </label>
+  );
+}

frontend/src/components/ui/common/OrganizationCard.tsx

@@ -1,7 +1,7 @@
 // src/components/ui/OrganizationCard.tsx
 import React from 'react';
 import { Building2, Beaker, ChevronRight } from 'lucide-react';
-import { Organization } from '@/types';
+import type { Organization } from '@/types/organization';
 
 interface OrganizationCardProps {
   organization: Organization;

frontend/src/components/ui/common/Sidebar.tsx

@@ -0,0 +1,83 @@
+'use client';
+
+import Link from 'next/link';
+import { memo, useMemo } from 'react';
+import { usePathname } from 'next/navigation';
+import {
+  LayoutDashboard,
+  Users,
+  Calendar,
+  UserCog,
+  FlaskConical,
+  FileText,
+  CreditCard,
+} from 'lucide-react';
+import { useAuth } from '@/lib/hooks/useAuth';
+import { canViewTab } from '@/shared/permissions';
+
+const menu = [
+  { name: 'Today', path: '/today', icon: LayoutDashboard, read: 'TAB_TODAY_READ' as const },
+  { name: 'Staff', path: '/staff', icon: UserCog, read: 'TAB_STAFF_READ' as const },
+  { name: 'Patients', path: '/patients', icon: Users, read: 'TAB_PATIENTS_READ' as const },
+  { name: 'Appointment', path: '/appointments', icon: Calendar, read: 'TAB_APPOINTMENTS_READ' as const },
+  { name: 'Treatment', path: '/treatment', icon: FlaskConical, read: 'TAB_TREATMENT_READ' as const },
+  { name: 'Billing', path: '/billing', icon: CreditCard, read: 'TAB_BILLING_READ' as const },
+  { name: 'Reports', path: '/reports', icon: FileText, read: 'TAB_REPORTS_READ' as const },
+];
+
+function Sidebar() {
+  const pathname = usePathname();
+  const { currentOrganization } = useAuth();
+  const counterpartLabel = currentOrganization?.type === 'LAB' ? 'Clinics' : 'Labs';
+
+  const visibleMenu = useMemo(
+    () => {
+      const withCounterpartTab = [
+        menu[0],
+        menu[1],
+        { name: counterpartLabel, path: '/lab', icon: FlaskConical, read: 'TAB_LAB_READ' as const },
+        menu[2],
+        menu[3],
+        menu[4],
+        menu[5],
+        menu[6],
+      ];
+      return withCounterpartTab.filter((item) => canViewTab(currentOrganization, item.read));
+    },
+    [counterpartLabel, currentOrganization],
+  );
+
+  return (
+    <aside className="w-64 bg-background-secondary/90 border-r border-border text-text-primary flex flex-col">
+      <div className="h-[71px] px-4 flex items-center">
+        <h1 className="text-lg font-medium tracking-tight">DyoLink</h1>
+      </div>
+      <div className="mx-4 border-b border-border/70" />
+
+      <nav className="flex flex-col gap-2 p-4">
+        {visibleMenu.map((item) => {
+          const Icon = item.icon;
+          const isActive = pathname === item.path;
+
+          return (
+            <Link
+              key={item.name}
+              href={item.path}
+              prefetch
+              className={`flex items-center gap-3 px-3 py-2.5 rounded-[var(--radius-sm)] border transition-colors ${
+                isActive
+                  ? 'bg-primary-soft border-primary/60 text-text-primary'
+                  : 'border-border/50 text-text-secondary hover:bg-background-card/70 hover:text-text-primary hover:border-border'
+              }`}
+            >
+              <Icon className="w-[18px] h-[18px] icon-flat" />
+              <span className="text-sm">{item.name}</span>
+            </Link>
+          );
+        })}
+      </nav>
+    </aside>
+  );
+}
+
+export default memo(Sidebar);

frontend/src/components/ui/dashboard/DashboardAccountMenu.tsx

@@ -0,0 +1,157 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import Link from 'next/link';
+import {
+  Settings,
+  AlertTriangle,
+  Building2,
+  CreditCard,
+  User,
+  LogOut,
+  ChevronDown,
+} from 'lucide-react';
+import { useAuth } from '@/lib/hooks/useAuth';
+import { authApi } from '@/lib/api/auth';
+import type { SubscriptionAlertData } from '@/types/subscription';
+
+function warningTooltip(data: SubscriptionAlertData | null): string {
+  if (!data?.showWarning) return '';
+  if (data.noActiveSubscription) return 'No active subscription — review Subscriptions';
+  if (data.trialExpired) return 'Trial ended — review Subscriptions';
+  if (data.trialEndingSoon) return 'Trial ending soon — review Subscriptions';
+  if (data.seatsLow) return 'Seats running low — review Subscriptions';
+  return 'Review Subscriptions';
+}
+
+export function DashboardAccountMenu() {
+  const { user, currentOrganization, logout } = useAuth();
+  const [open, setOpen] = useState(false);
+  const menuRef = useRef<HTMLDivElement>(null);
+  const [alert, setAlert] = useState<SubscriptionAlertData | null>(null);
+  const isOwner = currentOrganization?.isOwner ?? false;
+
+  useEffect(() => {
+    const onDocClick = (e: MouseEvent) => {
+      if (menuRef.current && !menuRef.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener('mousedown', onDocClick);
+    return () => document.removeEventListener('mousedown', onDocClick);
+  }, []);
+
+  useEffect(() => {
+    if (!isOwner || !currentOrganization) {
+      setAlert(null);
+      return;
+    }
+    let cancelled = false;
+    void (async () => {
+      try {
+        const res = await authApi.getSubscriptionAlert();
+        if (!cancelled && res.success) setAlert(res.data);
+      } catch {
+        if (!cancelled) setAlert(null);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [isOwner, currentOrganization?.id]);
+
+  const showWarning = Boolean(isOwner && alert?.showWarning);
+  const tooltip = useMemo(() => warningTooltip(alert), [alert]);
+
+  const handleLogout = useCallback(() => {
+    setOpen(false);
+    void logout();
+  }, [logout]);
+
+  return (
+    <div className="relative z-[120]" ref={menuRef}>
+      <button
+        type="button"
+        onClick={() => setOpen((v) => !v)}
+        className="inline-flex items-center gap-2 rounded-[var(--radius-md)] border border-border/70 px-3 py-2 text-sm text-text-primary hover:bg-background-card/80 transition-colors"
+        aria-expanded={open}
+        aria-haspopup="menu"
+      >
+        <span className="relative inline-flex shrink-0" title={showWarning ? tooltip : undefined}>
+          <Settings className="h-5 w-5 icon-flat" aria-hidden />
+          {showWarning && (
+            <span
+              className="absolute -right-1 -top-1 flex h-3.5 w-3.5 items-center justify-center rounded-full bg-amber-500 ring-2 ring-background-secondary"
+              aria-label={tooltip}
+            >
+              <AlertTriangle className="h-2.5 w-2.5 text-amber-950" strokeWidth={2.5} />
+            </span>
+          )}
+        </span>
+        <span className="hidden sm:inline max-w-[160px] truncate">{user?.name}</span>
+        <ChevronDown className="h-4 w-4 text-text-muted shrink-0" aria-hidden />
+      </button>
+
+      {open && (
+        <div
+          role="menu"
+          className="absolute right-0 mt-2 w-72 rounded-[var(--radius-md)] border border-border bg-background-secondary/95 py-2 shadow-lg z-[200] backdrop-blur-sm"
+        >
+          <div className="px-3 py-2 border-b border-border/60">
+            <p className="text-xs text-text-muted">Signed in</p>
+            <p className="text-sm font-medium truncate">{user?.email}</p>
+            <p className="text-xs text-text-secondary mt-1 truncate">
+              {currentOrganization?.name}
+            </p>
+          </div>
+
+          <div className="py-1">
+            <Link
+              href="/settings/organizations"
+              role="menuitem"
+              className="flex items-center gap-3 px-3 py-2.5 text-sm text-text-primary hover:bg-background-card/70"
+              onClick={() => setOpen(false)}
+            >
+              <Building2 className="h-4 w-4 icon-flat shrink-0" />
+              Switch organization
+            </Link>
+
+            {isOwner && (
+              <Link
+                href="/settings/subscriptions"
+                role="menuitem"
+                className="flex items-center gap-3 px-3 py-2.5 text-sm text-text-primary hover:bg-background-card/70"
+                onClick={() => setOpen(false)}
+              >
+                <CreditCard className="h-4 w-4 icon-flat shrink-0" />
+                Subscriptions
+              </Link>
+            )}
+
+            <Link
+              href="/settings/account"
+              role="menuitem"
+              className="flex items-center gap-3 px-3 py-2.5 text-sm text-text-primary hover:bg-background-card/70"
+              onClick={() => setOpen(false)}
+            >
+              <User className="h-4 w-4 icon-flat shrink-0" />
+              Account
+            </Link>
+          </div>
+
+          <div className="border-t border-border/60 pt-1">
+            <button
+              type="button"
+              role="menuitem"
+              className="flex w-full items-center gap-3 px-3 py-2.5 text-sm text-text-secondary hover:bg-background-card/70 hover:text-text-primary"
+              onClick={handleLogout}
+            >
+              <LogOut className="h-4 w-4 icon-flat shrink-0" />
+              Log out
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/components/ui/organization/OrganizationSelectorContent.tsx

@@ -0,0 +1,162 @@
+'use client';
+
+import { useState } from 'react';
+import { useAuth } from '@/lib/hooks/useAuth';
+import { Building2, Beaker, Mail, Plus } from 'lucide-react';
+import { Input } from '@/components/ui/common/Input';
+import { Button } from '@/components/ui/common/Button';
+
+export function OrganizationSelectorContent() {
+  const { organizations, selectOrganization, createOrganization, isLoading, error, clearError } = useAuth();
+  const [isCreateOpen, setIsCreateOpen] = useState(false);
+  const [organizationName, setOrganizationName] = useState('');
+  const [organizationEmail, setOrganizationEmail] = useState('');
+  const [organizationType, setOrganizationType] = useState<'CLINIC' | 'LAB'>('CLINIC');
+
+  const getIcon = (type: string) =>
+    type === 'CLINIC' ? <Building2 className="h-8 w-8 icon-flat" /> : <Beaker className="h-8 w-8 icon-flat" />;
+
+  const handleCreateOrganization = async () => {
+    try {
+      clearError();
+      const createdId = await createOrganization(
+        organizationName.trim(),
+        organizationEmail.trim(),
+        organizationType,
+      );
+      setOrganizationName('');
+      setOrganizationEmail('');
+      setOrganizationType('CLINIC');
+      setIsCreateOpen(false);
+      await selectOrganization(createdId);
+    } catch {
+      // handled by auth context
+    }
+  };
+
+  if (isLoading) {
+    return <p className="text-text-secondary">Loading...</p>;
+  }
+
+  return (
+    <div className="space-y-6">
+      <div className="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-4">
+        <div>
+          <h1 className="text-3xl font-semibold text-text-primary">Organizations</h1>
+          <p className="text-text-secondary mt-2">
+            Select an organization to continue, or create a new one.
+          </p>
+        </div>
+        <Button
+          type="button"
+          variant={isCreateOpen ? 'outline' : 'primary'}
+          onClick={() => {
+            clearError();
+            setIsCreateOpen((prev) => !prev);
+          }}
+        >
+          <Plus className="h-4 w-4 mr-2 icon-flat" />
+          {isCreateOpen ? 'Cancel' : 'Create Organization'}
+        </Button>
+      </div>
+
+      {isCreateOpen && (
+        <div className="surface-card p-6 space-y-4">
+          <Input
+            label="Organization name"
+            value={organizationName}
+            onChange={(event) => setOrganizationName(event.target.value)}
+            placeholder="Sunshine Dental Clinic"
+            icon={<Building2 className="h-5 w-5 icon-flat" />}
+          />
+          <Input
+            label="Organization email"
+            value={organizationEmail}
+            onChange={(event) => setOrganizationEmail(event.target.value)}
+            placeholder="contact@sunshineclinic.com"
+            type="email"
+            icon={<Mail className="h-5 w-5 icon-flat" />}
+          />
+          <div>
+            <label className="block text-sm font-medium text-text-secondary mb-2">
+              Organization type
+            </label>
+            <div className="grid grid-cols-2 gap-3">
+              <button
+                type="button"
+                onClick={() => setOrganizationType('CLINIC')}
+                className={`p-3 border rounded-[var(--radius-md)] text-sm ${
+                  organizationType === 'CLINIC'
+                    ? 'border-primary/60 bg-primary-soft text-text-primary'
+                    : 'border-border text-text-secondary hover:border-border-strong'
+                }`}
+              >
+                Dental Clinic
+              </button>
+              <button
+                type="button"
+                onClick={() => setOrganizationType('LAB')}
+                className={`p-3 border rounded-[var(--radius-md)] text-sm ${
+                  organizationType === 'LAB'
+                    ? 'border-primary/60 bg-primary-soft text-text-primary'
+                    : 'border-border text-text-secondary hover:border-border-strong'
+                }`}
+              >
+                Dental Lab
+              </button>
+            </div>
+          </div>
+          {error && (
+            <div className="p-3 bg-red-950/30 border border-red-600/40 rounded-[var(--radius-md)]">
+              <p className="text-sm text-red-600">{error}</p>
+            </div>
+          )}
+          <div className="flex justify-end">
+            <Button
+              type="button"
+              variant="primary"
+              onClick={handleCreateOrganization}
+              isLoading={isLoading}
+              disabled={!organizationName.trim() || !organizationEmail.trim()}
+            >
+              Create and Continue
+            </Button>
+          </div>
+        </div>
+      )}
+
+      {!organizations.length ? (
+        <div className="surface-card p-8 text-center">
+          <p className="text-text-secondary">No organizations found. Create your first one to continue.</p>
+        </div>
+      ) : (
+        <div className="grid gap-4">
+          {organizations.map((org) => (
+            <button
+              key={org.id}
+              onClick={() => selectOrganization(org.id)}
+              className="surface-card p-6 transition-all text-left flex items-center gap-4 hover:border-primary/60"
+            >
+              <div className="p-3 bg-primary-soft rounded-[var(--radius-sm)] text-primary">
+                {getIcon(org.type)}
+              </div>
+
+              <div className="flex-1">
+                <h3 className="text-lg font-semibold text-text-primary">
+                  {org.name}
+                </h3>
+                <p className="text-sm text-text-secondary">
+                  {org.type === 'CLINIC' ? 'Dental Clinic' : 'Dental Lab'}
+                </p>
+              </div>
+
+              <div className="text-primary text-sm">
+                Continue →
+              </div>
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/components/ui/patient/CreatePatientModal.tsx

@@ -0,0 +1,69 @@
+'use client';
+
+import { Button } from '@/components/ui/common/Button';
+import { Input } from '@/components/ui/common/Input';
+import { CreatePatientInput } from '@/types/patient';
+
+interface CreatePatientModalProps {
+  isOpen: boolean;
+  formData: CreatePatientInput;
+  onChange: (patch: Partial<CreatePatientInput>) => void;
+  onSubmit: () => void;
+  onClose: () => void;
+  loading?: boolean;
+}
+
+export function CreatePatientModal({
+  isOpen,
+  formData,
+  onChange,
+  onSubmit,
+  onClose,
+  loading = false,
+}: CreatePatientModalProps) {
+  if (!isOpen) {
+    return null;
+  }
+
+  return (
+    <div className="surface-card p-4 space-y-3">
+      <div className="grid grid-cols-1 md:grid-cols-2 gap-3">
+        <Input
+          label="First name"
+          value={formData.firstName || ''}
+          onChange={(e) => onChange({ firstName: e.target.value })}
+        />
+        <Input
+          label="Last name"
+          value={formData.lastName || ''}
+          onChange={(e) => onChange({ lastName: e.target.value })}
+        />
+        <Input
+          label="Phone"
+          value={formData.phone || ''}
+          onChange={(e) => onChange({ phone: e.target.value })}
+        />
+        <Input
+          label="Email"
+          type="email"
+          value={formData.email || ''}
+          onChange={(e) => onChange({ email: e.target.value })}
+        />
+      </div>
+
+      <div className="flex gap-2">
+        <Button
+          variant="primary"
+          onClick={onSubmit}
+          isLoading={loading}
+          disabled={!formData.firstName || !formData.lastName}
+        >
+          Save Patient
+        </Button>
+        <Button variant="ghost" onClick={onClose}>
+          Cancel
+        </Button>
+      </div>
+    </div>
+  );
+}

frontend/src/components/ui/patient/PatientSearchSelect.tsx

@@ -0,0 +1,63 @@
+'use client';
+
+import { Search } from 'lucide-react';
+import { Input } from '@/components/ui/common/Input';
+import { Patient } from '@/types/patient';
+
+interface PatientSearchSelectProps {
+  search: string;
+  onSearchChange: (value: string) => void;
+  patients: Patient[];
+  selectedPatientId?: string;
+  onSelectPatient: (patient: Patient) => void;
+  loading?: boolean;
+}
+
+export function PatientSearchSelect({
+  search,
+  onSearchChange,
+  patients,
+  selectedPatientId,
+  onSelectPatient,
+  loading = false,
+}: PatientSearchSelectProps) {
+  return (
+    <div className="surface-card p-4 space-y-4">
+      <Input
+        placeholder="Search patients by name, phone, email"
+        value={search}
+        onChange={(e) => onSearchChange(e.target.value)}
+        icon={<Search className="h-4 w-4 icon-flat" />}
+      />
+
+      <div className="space-y-2 max-h-80 overflow-y-auto">
+        {loading && <p className="text-sm text-text-muted">Loading patients...</p>}
+
+        {!loading && patients.length === 0 && (
+          <p className="text-sm text-text-muted">No patients found for this search.</p>
+        )}
+
+        {patients.map((patient) => {
+          const isSelected = selectedPatientId === patient.id;
+          return (
+            <button
+              key={patient.id}
+              type="button"
+              onClick={() => onSelectPatient(patient)}
+              className={`w-full text-left rounded-[var(--radius-sm)] border px-3 py-2 transition-colors ${
+                isSelected
+                  ? 'bg-primary-soft border-primary/60'
+                  : 'border-border/60 hover:bg-background-card/70'
+              }`}
+            >
+              <p className="text-sm font-medium text-text-primary">
+                {patient.firstName} {patient.lastName}
+              </p>
+              <p className="text-xs text-text-muted">{patient.phone || patient.email || 'No contact'}</p>
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

frontend/src/components/ui/patient/PatientSummaryCard.tsx

@@ -0,0 +1,28 @@
+import { Patient } from '@/types/patient';
+
+interface PatientSummaryCardProps {
+  patient?: Patient;
+}
+
+export function PatientSummaryCard({ patient }: PatientSummaryCardProps) {
+  if (!patient) {
+    return (
+      <div className="surface-card p-4">
+        <p className="text-sm text-text-muted">Select a patient to view details.</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="surface-card p-4 space-y-2">
+      <h2 className="text-lg font-semibold text-text-primary">
+        {patient.firstName} {patient.lastName}
+      </h2>
+      <p className="text-sm text-text-secondary">Phone: {patient.phone || '-'}</p>
+      <p className="text-sm text-text-secondary">Email: {patient.email || '-'}</p>
+      <p className="text-sm text-text-secondary">
+        Status: {patient.isActive ? 'Active' : 'Inactive'}
+      </p>
+    </div>
+  );
+}

frontend/src/components/ui/patient/TreatmentHistoryPreview.tsx

@@ -0,0 +1,37 @@
+import { TreatmentHistoryItem } from '@/types/patient';
+
+interface TreatmentHistoryPreviewProps {
+  items: TreatmentHistoryItem[];
+  loading?: boolean;
+}
+
+export function TreatmentHistoryPreview({ items, loading = false }: TreatmentHistoryPreviewProps) {
+  return (
+    <div className="surface-card p-4 space-y-3">
+      <h3 className="text-base font-semibold text-text-primary">Treatment History</h3>
+
+      {loading && <p className="text-sm text-text-muted">Loading treatment history...</p>}
+
+      {!loading && items.length === 0 && (
+        <p className="text-sm text-text-muted">No treatment history yet.</p>
+      )}
+
+      <div className="space-y-2">
+        {items.map((item) => (
+          <div key={item.id} className="border border-border/60 rounded-[var(--radius-sm)] p-3">
+            <div className="flex items-center justify-between">
+              <p className="text-sm font-medium text-text-primary">{item.title}</p>
+              <p className="text-xs text-text-muted">
+                {new Date(item.treatmentAt).toLocaleDateString()}
+              </p>
+            </div>
+            <p className="text-xs text-text-secondary mt-1">
+              Status: {item.status}
+              {item.tooth ? ` | Tooth: ${item.tooth}` : ''}
+            </p>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

frontend/src/lib/api/auth.ts

@@ -1,6 +1,7 @@
 // src/lib/api/auth.ts
 import { apiClient } from './client';
-import { AuthResponse, TrialRegistrationData, LoginData } from '@/types';
+import type { AuthResponse, TrialRegistrationData, LoginData } from '@/types/auth';
+import type { SubscriptionAlertData } from '@/types/subscription';
 
 export const authApi = {
   // Register a new trial organization
@@ -21,12 +22,32 @@ export const authApi = {
     return response.data;
   },
 
+  /** Owner-only meaningful data; staff always gets showWarning: false */
+  getSubscriptionAlert: async (): Promise<{
+    success: boolean;
+    data: SubscriptionAlertData;
+  }> => {
+    const response = await apiClient.get('/auth/subscription-alert');
+    return response.data;
+  },
+
   // Select organization
   selectOrganization: async (organizationId: string): Promise<any> => {
     const response = await apiClient.post('/auth/select-organization', { organizationId });
     return response.data;
   },
 
+  // Create organization for current user
+  createOrganization: async (data: {
+    organizationName: string;
+    organizationEmail: string;
+    organizationType: 'CLINIC' | 'LAB';
+    planName?: string;
+  }): Promise<any> => {
+    const response = await apiClient.post('/auth/organizations', data);
+    return response.data;
+  },
+
   // Logout
   logout: async (): Promise<void> => {
     await apiClient.post('/auth/logout');

frontend/src/lib/api/client.ts

@@ -1,6 +1,6 @@
 // src/lib/api/client.ts
 import axios, { AxiosError, InternalAxiosRequestConfig } from 'axios';
-import { ApiError } from '@/types';
+import type { ApiError } from '@/types/api';
 
 interface CustomAxiosRequestConfig extends InternalAxiosRequestConfig {
   _retry?: boolean;

frontend/src/lib/api/patients.ts

@@ -0,0 +1,43 @@
+import { apiClient } from './client';
+import {
+  CreatePatientInput,
+  CreateTreatmentHistoryInput,
+  Patient,
+  PatientsListResponse,
+  TreatmentHistoryItem,
+} from '@/types/patient';
+
+export const patientsApi = {
+  list: async (params?: { q?: string; page?: number; limit?: number }): Promise<PatientsListResponse> => {
+    const response = await apiClient.get('/patients', { params });
+    return response.data;
+  },
+
+  create: async (data: CreatePatientInput): Promise<{ success: boolean; data: Patient }> => {
+    const response = await apiClient.post('/patients', data);
+    return response.data;
+  },
+
+  getOne: async (id: string): Promise<{ success: boolean; data: Patient }> => {
+    const response = await apiClient.get(`/patients/${id}`);
+    return response.data;
+  },
+
+  listTreatments: async (
+    patientId: string,
+    limit = 20,
+  ): Promise<{ success: boolean; data: TreatmentHistoryItem[] }> => {
+    const response = await apiClient.get(`/patients/${patientId}/treatments`, {
+      params: { limit },
+    });
+    return response.data;
+  },
+
+  addTreatment: async (
+    patientId: string,
+    data: CreateTreatmentHistoryInput,
+  ): Promise<{ success: boolean; data: TreatmentHistoryItem }> => {
+    const response = await apiClient.post(`/patients/${patientId}/treatments`, data);
+    return response.data;
+  },
+};

frontend/src/lib/api/staff.ts

@@ -0,0 +1,94 @@
+import { apiClient } from './client';
+
+export interface StaffMemberDto {
+  id: string;
+  userId: string;
+  email: string;
+  name: string;
+  isOwner: boolean;
+  isActive: boolean;
+  invitationStatus: 'ACTIVE' | 'PENDING' | 'EXPIRED';
+  invitedAt: string | null;
+  acceptedAt: string | null;
+  permissions: string[] | null;
+}
+
+export interface StaffListResponse {
+  success: boolean;
+  data: {
+    members: StaffMemberDto[];
+    seats: {
+      used: number;
+      limit: number | null;
+      unlimited: boolean;
+    };
+  };
+}
+
+export interface InviteStaffResponse {
+  success: boolean;
+  data: {
+    membershipId: string;
+    userId: string;
+    email: string;
+    invitationId: string | null;
+    invitationUrl: string | null;
+    invitationStatus: 'PENDING' | 'ACCEPTED';
+  };
+}
+
+export interface PreviewInviteResponse {
+  success: boolean;
+  data: {
+    email: string;
+    name: string;
+    organizationName: string;
+    expiresAt: string;
+    status: 'PENDING' | 'ACCEPTED';
+  };
+}
+
+export const staffApi = {
+  list: async (): Promise<StaffListResponse> => {
+    const response = await apiClient.get('/staff');
+    return response.data;
+  },
+
+  invite: async (body: {
+    email: string;
+    name: string;
+    permissionNames: string[];
+  }): Promise<InviteStaffResponse> => {
+    const response = await apiClient.post('/staff/invite', body);
+    return response.data;
+  },
+
+  previewInvite: async (token: string): Promise<PreviewInviteResponse> => {
+    const response = await apiClient.get(`/staff/invitations/preview?token=${encodeURIComponent(token)}`);
+    return response.data;
+  },
+
+  acceptInvite: async (body: {
+    token: string;
+    password: string;
+    name: string;
+  }): Promise<{ success: boolean; message: string; data: { email: string } }> => {
+    const response = await apiClient.post('/staff/invitations/accept', body);
+    return response.data;
+  },
+
+  updateMember: async (
+    membershipId: string,
+    body: { name?: string; permissionNames?: string[] },
+  ): Promise<{ success: boolean; message: string }> => {
+    const response = await apiClient.patch(`/staff/members/${membershipId}`, body);
+    return response.data;
+  },
+
+  removeMember: async (
+    membershipId: string,
+  ): Promise<{ success: boolean; message: string }> => {
+    const response = await apiClient.delete(`/staff/members/${membershipId}`);
+    return response.data;
+  },
+};

frontend/src/lib/hooks/useAuth.tsx

@@ -1,9 +1,9 @@
 'use client';
 
-import React, { createContext, useContext, useEffect, useState } from 'react';
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';
 import { useRouter } from 'next/navigation';
 import { authApi } from '@/lib/api/auth';
-import { User, Organization } from '@/types';
+import { User, Organization } from '@/types/organization';
 
 interface AuthContextType {
   user: User | null;
@@ -17,11 +17,18 @@ interface AuthContextType {
     password: string,
     name: string,
     organizationName: string,
+    organizationEmail: string,
     organizationType: 'CLINIC' | 'LAB'
   ) => Promise<void>;
   login: (email: string, password: string) => Promise<void>;
   logout: () => Promise<void>;
   selectOrganization: (orgId: string) => Promise<void>;
+  createOrganization: (
+    organizationName: string,
+    organizationEmail: string,
+    organizationType: 'CLINIC' | 'LAB',
+    planName?: string,
+  ) => Promise<string>;
   clearError: () => void;
 }
 
@@ -37,11 +44,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
 
   const router = useRouter();
 
-  useEffect(() => {
-    checkAuth();
-  }, []);
-
-  const normalizeProfilePayload = (payload: any): { user: User | null; organizations: Organization[] } => {
+  const normalizeProfilePayload = useCallback((payload: any): { user: User | null; organizations: Organization[] } => {
     const organizations = payload?.organizations || [];
 
     if (payload?.user) {
@@ -60,9 +63,9 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
     }
 
     return { user: null, organizations };
-  };
+  }, []);
 
-  const checkAuth = async () => {
+  const checkAuth = useCallback(async () => {
     try {
       setIsLoading(true);
 
@@ -77,11 +80,18 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
         const storedOrgId = localStorage.getItem('currentOrganizationId');
         if (storedOrgId && orgs.length > 0) {
           const org = orgs.find(o => o.id === storedOrgId);
-          if (org) setCurrentOrganization(org);
-          else setCurrentOrganization(null);
+          if (org) {
+            setCurrentOrganization(org);
+            // Ensure cookie token carries organizationId for org-scoped APIs.
+            await authApi.selectOrganization(org.id);
+          } else {
+            setCurrentOrganization(null);
+          }
         } else if (orgs.length === 1 && userData) {
           setCurrentOrganization(orgs[0]);
           localStorage.setItem('currentOrganizationId', orgs[0].id);
+          // Keep JWT in sync with selected org even for single-org users.
+          await authApi.selectOrganization(orgs[0].id);
         } else {
           setCurrentOrganization(null);
         }
@@ -96,14 +106,19 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
       setIsLoading(false);
       setIsAuthReady(true);
     }
-  };
+  }, [normalizeProfilePayload]);
+
+  useEffect(() => {
+    void checkAuth();
+  }, [checkAuth]);
 
   // ✅ REGISTER
-  const registerTrial = async (
+  const registerTrial = useCallback(async (
     email: string,
     password: string,
     name: string,
     organizationName: string,
+    organizationEmail: string,
     organizationType: 'CLINIC' | 'LAB'
   ) => {
     try {
@@ -115,6 +130,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
         password,
         name,
         organizationName,
+        organizationEmail,
         organizationType,
       });
 
@@ -125,6 +141,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
 
       if (orgs.length === 1) {
         const org = orgs[0];
+        await authApi.selectOrganization(org.id);
         setCurrentOrganization(org);
         localStorage.setItem('currentOrganizationId', org.id);
         router.push('/today');
@@ -139,10 +156,10 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
     } finally {
       setIsLoading(false);
     }
-  };
+  }, [router]);
 
   // ✅ LOGIN
-  const login = async (email: string, password: string) => {
+  const login = useCallback(async (email: string, password: string) => {
     try {
       setIsLoading(true);
       setError(null);
@@ -156,6 +173,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
 
       if (orgs.length === 1) {
         const org = orgs[0];
+        await authApi.selectOrganization(org.id);
         setCurrentOrganization(org);
         localStorage.setItem('currentOrganizationId', org.id);
         router.push('/today');
@@ -169,17 +187,28 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
     } finally {
       setIsLoading(false);
     }
-  };
+  }, [router]);
 
-  const logout = async () => {
-    localStorage.clear();
-    setUser(null);
-    setOrganizations([]);
-    setCurrentOrganization(null);
-    router.push('/');
-  };
+  const logout = useCallback(async () => {
+    try {
+      // Important: clear auth cookies/session on the server first,
+      // otherwise middleware may still treat the user as authenticated.
+      await authApi.logout();
+    } catch (err) {
+      console.error('Logout API failed:', err);
+    } finally {
+      localStorage.clear();
+      setUser(null);
+      setOrganizations([]);
+      setCurrentOrganization(null);
+      setError(null);
+      setIsAuthReady(true);
+      router.replace('/');
+      router.refresh();
+    }
+  }, [router]);
 
-  const selectOrganization = async (orgId: string) => {
+  const selectOrganization = useCallback(async (orgId: string) => {
     try {
       setIsLoading(true);
 
@@ -189,7 +218,14 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
 
       localStorage.setItem('currentOrganizationId', organization.id);
 
-      setCurrentOrganization(organization);
+      setCurrentOrganization({
+        id: organization.id,
+        name: organization.name,
+        type: organization.type as Organization['type'],
+        isOwner: Boolean((organization as { isOwner?: boolean }).isOwner),
+        permissions: (organization as { permissions?: string[] }).permissions,
+        plan: (organization as { plan?: Organization['plan'] }).plan,
+      });
 
       router.push('/today');
 
@@ -199,26 +235,76 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
     } finally {
       setIsLoading(false);
     }
-  };
+  }, [router]);
 
-  const clearError = () => setError(null);
+  const createOrganization = useCallback(async (
+    organizationName: string,
+    organizationEmail: string,
+    organizationType: 'CLINIC' | 'LAB',
+    planName?: string,
+  ) => {
+    try {
+      setIsLoading(true);
+      setError(null);
+
+      const createResponse = await authApi.createOrganization({
+        organizationName,
+        organizationEmail,
+        organizationType,
+        planName,
+      });
+
+      const profileResponse = await authApi.getProfile();
+      if (profileResponse.success) {
+        const { user: userData, organizations: orgs } = normalizeProfilePayload(profileResponse.data);
+        setUser(userData);
+        setOrganizations(orgs);
+      }
+
+      return createResponse.data.organization.id as string;
+    } catch (err: any) {
+      setError(err.message || 'Failed to create organization');
+      throw err;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [normalizeProfilePayload]);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const contextValue = useMemo(
+    () => ({
+      user,
+      organizations,
+      currentOrganization,
+      isLoading,
+      isAuthReady,
+      error,
+      registerTrial,
+      login,
+      logout,
+      selectOrganization,
+      createOrganization,
+      clearError,
+    }),
+    [
+      user,
+      organizations,
+      currentOrganization,
+      isLoading,
+      isAuthReady,
+      error,
+      registerTrial,
+      login,
+      logout,
+      selectOrganization,
+      createOrganization,
+      clearError,
+    ],
+  );
 
   return (
-    <AuthContext.Provider
-      value={{
-        user,
-        organizations,
-        currentOrganization,
-        isLoading,
-        isAuthReady, // ✅ expose it
-        error,
-        registerTrial,
-        login,
-        logout,
-        selectOrganization,
-        clearError,
-      }}
-    >
+    <AuthContext.Provider value={contextValue}>
       {children}
     </AuthContext.Provider>
   );

frontend/src/proxy.ts

@@ -1,32 +1,22 @@
-
 import { NextResponse } from 'next/server';
 import type { NextRequest } from 'next/server';
 
 const publicRoutes = ['/', '/login', '/register', '/terms', '/privacy', '/forgot-password'];
-const authOnlyRoutes = ['/login', '/register']; // routes that should NOT be accessed when logged in
 
-export function middleware(request: NextRequest) {
+export function proxy(request: NextRequest) {
   const { pathname } = request.nextUrl;
   const token = request.cookies.get('accessToken')?.value;
   const isAuthenticated = !!token;
 
-  // If a logged-in user opens home, send them to dashboard.
   if (isAuthenticated && pathname === '/') {
     return NextResponse.redirect(new URL('/today', request.url));
   }
 
-  // Always allow public routes first
   if (publicRoutes.includes(pathname)) {
-    // If user is already logged in and tries to access login/register → redirect to dashboard
-    if (isAuthenticated && authOnlyRoutes.includes(pathname)) {
-      return NextResponse.redirect(new URL('/today', request.url));
-    }
     return NextResponse.next();
   }
 
-  // Protected routes: redirect to login if no token
   if (!isAuthenticated) {
-    // Prevent loop: if somehow redirecting to login from login, just continue
     if (pathname === '/login') {
       return NextResponse.next();
     }
@@ -43,4 +33,4 @@ export const config = {
   matcher: [
     '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
   ],
-};
+};

frontend/src/shared/permissions.ts

@@ -0,0 +1,50 @@
+import type { Organization } from '@/types/organization';
+
+const ROUTE_TAB_READ: { prefix: string; permission: string }[] = [
+  { prefix: '/today', permission: 'TAB_TODAY_READ' },
+  { prefix: '/staff', permission: 'TAB_STAFF_READ' },
+  { prefix: '/lab', permission: 'TAB_LAB_READ' },
+  { prefix: '/patients', permission: 'TAB_PATIENTS_READ' },
+  { prefix: '/appointments', permission: 'TAB_APPOINTMENTS_READ' },
+  { prefix: '/treatment', permission: 'TAB_TREATMENT_READ' },
+  { prefix: '/billing', permission: 'TAB_BILLING_READ' },
+  { prefix: '/reports', permission: 'TAB_REPORTS_READ' },
+];
+
+export function hasPermission(org: Organization | null, permission: string): boolean {
+  if (!org) return false;
+  return Boolean(org.permissions?.includes(permission));
+}
+
+/** Sidebar / route guard: READ access to a tab */
+export function canViewTab(org: Organization | null, readPermission: string): boolean {
+  return hasPermission(org, readPermission);
+}
+
+export function getRequiredReadPermissionForPath(pathname: string): string | null {
+  for (const { prefix, permission } of ROUTE_TAB_READ) {
+    if (pathname === prefix || pathname.startsWith(`${prefix}/`)) {
+      return permission;
+    }
+  }
+  return null;
+}
+
+/** First dashboard route the user may open (ordered). Fallback: account settings. */
+export function firstAccessibleDashboardPath(org: Organization | null): string {
+  if (!org) return '/today';
+  for (const { prefix, permission } of ROUTE_TAB_READ) {
+    if (hasPermission(org, permission)) return prefix;
+  }
+  return '/settings/account';
+}
+
+export function canEditStaff(org: Organization | null): boolean {
+  return hasPermission(org, 'TAB_STAFF_EDIT');
+}
+
+export function canViewStaff(org: Organization | null): boolean {
+  return (
+    hasPermission(org, 'TAB_STAFF_READ') || hasPermission(org, 'TAB_STAFF_EDIT')
+  );
+}

frontend/src/styles/globals.css

@@ -2,9 +2,9 @@
 
 /* Light theme tokens (future-ready) */
 :root[data-theme="light"] {
-  --radius-sm: 6px;
-  --radius-md: 8px;
-  --radius-lg: 12px;
+  --radius-sm: 4px;
+  --radius-md: 6px;
+  --radius-lg: 8px;
 
   --color-background-primary: #f6f9fc;
   --color-background-secondary: #ffffff;
@@ -45,7 +45,7 @@
   --color-primary: #09a9bc;
   --color-primary-contrast: #001117;
   --color-primary-soft: rgba(9, 169, 188, 0.2);
-  --color-icon: #f3bb4b;
+  --color-icon: #e1bc72;
 }
 
 /* Default theme = dark */

frontend/src/types/api.ts

@@ -0,0 +1,5 @@
+export interface ApiError {
+  statusCode: number;
+  message: string | string[];
+  error?: string;
+}

frontend/src/types/auth.ts

@@ -0,0 +1,25 @@
+import type { Organization, User } from './organization';
+
+export interface AuthResponse {
+  success: boolean;
+  data: {
+    accessToken: string;
+    refreshToken: string;
+    user: User;
+    organizations: Organization[];
+  };
+}
+
+export interface TrialRegistrationData {
+  email: string;
+  password: string;
+  name: string;
+  organizationName: string;
+  organizationEmail: string;
+  organizationType: 'CLINIC' | 'LAB';
+}
+
+export interface LoginData {
+  email: string;
+  password: string;
+}

frontend/src/types/index.ts

@@ -1,46 +1,5 @@
-// src/types/index.ts
-export interface User {
-  id: string;
-  email: string;
-  name: string;
-}
-
-export interface Organization {
-  id: string;
-  name: string;
-  type: 'CLINIC' | 'LAB';
-  isOwner: boolean;
-  plan?: {
-    name: string;
-    maxUsers: number;
-  };
-}
-
-export interface AuthResponse {
-  success: boolean;
-  data: {
-    accessToken: string;
-    refreshToken: string;
-    user: User;
-    organizations: Organization[];
-  };
-}
-
-export interface TrialRegistrationData {
-  email: string;
-  password: string;
-  name: string;
-  organizationName: string;
-  organizationType: 'CLINIC' | 'LAB';
-}
-
-export interface LoginData {
-  email: string;
-  password: string;
-}
-
-export interface ApiError {
-  statusCode: number;
-  message: string | string[];
-  error?: string;
-}
+export * from './organization';
+export * from './subscription';
+export * from './auth';
+export * from './api';
+export * from './patient';

frontend/src/types/organization.ts

@@ -0,0 +1,20 @@
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+}
+
+export interface OrganizationPlan {
+  name: string;
+  maxUsers: number;
+  price?: number;
+}
+
+export interface Organization {
+  id: string;
+  name: string;
+  type: 'CLINIC' | 'LAB';
+  isOwner: boolean;
+  permissions?: string[];
+  plan?: OrganizationPlan;
+}

frontend/src/types/patient.ts

@@ -0,0 +1,57 @@
+export interface Patient {
+  id: string;
+  organizationId: string;
+  firstName: string;
+  lastName: string;
+  phone?: string | null;
+  email?: string | null;
+  dateOfBirth?: string | null;
+  notes?: string | null;
+  isActive: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface TreatmentHistoryItem {
+  id: string;
+  patientId: string;
+  title: string;
+  status: string;
+  treatmentAt: string;
+  tooth?: string | null;
+  notes?: string | null;
+  totalCost?: number | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreatePatientInput {
+  firstName: string;
+  lastName: string;
+  phone?: string;
+  email?: string;
+  dateOfBirth?: string;
+  notes?: string;
+}
+
+export interface CreateTreatmentHistoryInput {
+  title: string;
+  status: string;
+  treatmentAt: string;
+  tooth?: string;
+  notes?: string;
+  totalCost?: number;
+}
+
+export interface PatientsListResponse {
+  success: boolean;
+  data: {
+    items: Patient[];
+    pagination: {
+      page: number;
+      limit: number;
+      total: number;
+      totalPages: number;
+    };
+  };
+}

frontend/src/types/subscription.ts

@@ -0,0 +1,14 @@
+/** GET /auth/subscription-alert — owners only get meaningful flags */
+export interface SubscriptionAlertData {
+  showWarning: boolean;
+  noActiveSubscription?: boolean;
+  seatsLow: boolean;
+  trialEndingSoon: boolean;
+  trialExpired: boolean;
+  seatsUsed?: number;
+  seatsLimit?: number | null;
+  daysUntilTrialEnd?: number | null;
+  trialEndsAt?: string | null;
+  daysUntilPlanEnd?: number | null;
+  planEndsAt?: string | null;
+}

infrastructure/.env.example

@@ -19,4 +19,7 @@ DOMAIN=dyolink.com
 # Frontend Environment (create frontend.env from this)
 # NEXT_PUBLIC_API_URL=/api
 # NEXT_PUBLIC_APP_NAME=Dyolink
-# NEXT_PUBLIC_APP_URL=https://dyolink.com
+# NEXT_PUBLIC_APP_URL=https://dyolink.com
+
+# --- Staging on your server (docker-compose.staging.yml) ---
+# See env.staging.example, database.staging.env.example, backend.staging.env.example

infrastructure/backend.staging.env.example

@@ -0,0 +1,12 @@
+# Copy to backend.staging.env — DATABASE_URL must match database.staging.env credentials.
+NODE_ENV=production
+PORT=3000
+
+DATABASE_URL=postgresql://postgres:changeme_staging_strong_password@postgres:5432/dyolink_db
+
+JWT_SECRET=replace_with_a_long_random_secret
+JWT_EXPIRES_IN=15m
+JWT_REFRESH_SECRET=another_long_random_secret_different_from_JWT_SECRET
+JWT_REFRESH_EXPIRES_IN=30d
+
+FRONTEND_URL=http://178.131.50.201:8088

infrastructure/database.staging.env.example

@@ -0,0 +1,4 @@
+# Copy to database.staging.env (do not commit real passwords).
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=changeme_staging_strong_password
+POSTGRES_DB=dyolink_db

infrastructure/deploy.registry.env.example

@@ -0,0 +1,19 @@
+# Template for manual pull-only deploy (when not using CI-generated deploy.registry.env).
+# CI workflow generates this file automatically; you normally only need secrets on disk.
+#
+# docker compose -f docker-compose.registry.yml --env-file deploy.registry.env up -d
+
+# --- Registry boundary (swap when moving Gitea → Docker Hub) ---
+# Gitea:  REGISTRY_PREFIX = <host>:<port>/<owner>
+# Hub:    REGISTRY_PREFIX = docker.io/<user>   (or your username for implicit hub)
+REGISTRY_PREFIX=178.131.50.201:3000/yourgiteauser
+
+# Short git SHA from CI, or "latest" after a manual pull of :latest
+IMAGE_TAG=latest
+
+# Host port published for nginx (URL = http://<your-ip>:<this-port>)
+STAGING_HTTP_PORT=8088
+
+# Absolute path on the server where database.staging.env and backend.staging.env live.
+# Use forward slashes on Windows. Same variable as Gitea Actions → DEPLOY_SECRETS_DIR.
+# DEPLOY_SECRETS_DIR=D:/dyolink/secrets

infrastructure/docker-compose.prod.yml

@@ -53,7 +53,7 @@ services:
         max-size: "10m"
         max-file: "3"
     healthcheck:
-      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/api/health', (r) => {if(r.statusCode!==200)process.exit(1)})"]
+      test: ["CMD", "node", "-e", "require('http').get('http://127.0.0.1:3000/api/health', (r) => {if(r.statusCode!==200)process.exit(1)})"]
       interval: 30s
       timeout: 10s
       retries: 3
@@ -81,7 +81,7 @@ services:
         max-size: "10m"
         max-file: "3"
     healthcheck:
-      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000', (r) => {if(r.statusCode!==200)process.exit(1)})"]
+      test: ["CMD", "node", "-e", "require('http').get('http://127.0.0.1:3000/', (r) => {if(r.statusCode!==200)process.exit(1)})"]
       interval: 30s
       timeout: 10s
       retries: 3