Build world-class WELLab AI-Enabled Research Platform

.dockerignore

@@ -0,0 +1,8 @@
+node_modules
+.git
+dist
+coverage
+__pycache__
+.env
+*.pyc
+.pytest_cache

.env.example

@@ -1,31 +1,59 @@
+# ======================
 # AWS Configuration
+# ======================
+# AWS region for DynamoDB, Cognito, and other services
 AWS_REGION=us-east-1
+# AWS account ID for resource ARNs
 AWS_ACCOUNT_ID=
 
-# DynamoDB
+# DynamoDB table configuration
 DYNAMODB_TABLE_PREFIX=wellab
 DYNAMODB_PUBLICATIONS_TABLE=wellab-publications
 DYNAMODB_PROJECTS_TABLE=wellab-projects
 
-# Cognito
+# ======================
+# Auth (Cognito)
+# ======================
+# Cognito User Pool ID from AWS Console
 COGNITO_USER_POOL_ID=
 COGNITO_CLIENT_ID=
 
+# JWT secret for local token signing (min 32 characters)
+JWT_SECRET=YOUR_KEY_HERE
+# Session secret for express-session (min 32 characters)
+SESSION_SECRET=YOUR_KEY_HERE
+
+# ======================
 # API Configuration
+# ======================
+# Backend API port and base URL
 API_PORT=3001
 API_BASE_URL=http://localhost:3001
 
-# Claude API (Anthropic)
-ANTHROPIC_API_KEY=sk-ant-xxxxx
+# CORS allowed origin (frontend URL)
+CORS_ORIGIN=http://localhost:5173
+
+# Logging level: debug, info, warn, error
+LOG_LEVEL=info
+
+# Claude API key from Anthropic (https://console.anthropic.com)
+ANTHROPIC_API_KEY=YOUR_KEY_HERE
 
+# ======================
 # Frontend
+# ======================
 VITE_API_BASE_URL=http://localhost:3001
 VITE_COGNITO_USER_POOL_ID=
 VITE_COGNITO_CLIENT_ID=
 
+# ======================
 # ML Service
+# ======================
+# Python ML API port and base URL
 ML_API_PORT=8000
 ML_API_BASE_URL=http://localhost:8000
 
+# ======================
 # Environment
+# ======================
 NODE_ENV=development

.eslintrc.json

@@ -33,8 +33,9 @@
   "rules": {
     "react/react-in-jsx-scope": "off",
     "@typescript-eslint/no-unused-vars": ["warn", { "argsIgnorePattern": "^_" }],
-    "@typescript-eslint/explicit-function-return-type": "off",
-    "@typescript-eslint/no-explicit-any": "warn"
+    "@typescript-eslint/explicit-function-return-type": "warn",
+    "@typescript-eslint/no-explicit-any": "error",
+    "@typescript-eslint/no-floating-promises": "error"
   },
   "ignorePatterns": ["dist/", "node_modules/", "coverage/"]
 }

.github/workflows/ci.yml

@@ -11,24 +11,49 @@ jobs:
     name: Lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/setup-node@60ecd5dd1b667a8e52112f999ebc6e0c8267832c # v4.0.2
         with:
           node-version: 20
-          cache: npm
+      - uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4.0.2
+        with:
+          path: node_modules
+          key: node-modules-${{ hashFiles('package-lock.json') }}
+          restore-keys: node-modules-
       - run: npm ci
       - run: npm run lint
 
+  type-check:
+    name: Type Check
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/setup-node@60ecd5dd1b667a8e52112f999ebc6e0c8267832c # v4.0.2
+        with:
+          node-version: 20
+      - uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4.0.2
+        with:
+          path: node_modules
+          key: node-modules-${{ hashFiles('package-lock.json') }}
+          restore-keys: node-modules-
+      - run: npm ci
+      - run: npx tsc --noEmit
+
   test-frontend:
     name: Test Frontend
     runs-on: ubuntu-latest
     needs: lint
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/setup-node@60ecd5dd1b667a8e52112f999ebc6e0c8267832c # v4.0.2
         with:
           node-version: 20
-          cache: npm
+      - uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4.0.2
+        with:
+          path: node_modules
+          key: node-modules-${{ hashFiles('package-lock.json') }}
+          restore-keys: node-modules-
       - run: npm ci
       - run: npm run build --workspace=src/frontend
 
@@ -37,11 +62,15 @@ jobs:
     runs-on: ubuntu-latest
     needs: lint
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/setup-node@60ecd5dd1b667a8e52112f999ebc6e0c8267832c # v4.0.2
         with:
           node-version: 20
-          cache: npm
+      - uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4.0.2
+        with:
+          path: node_modules
+          key: node-modules-${{ hashFiles('package-lock.json') }}
+          restore-keys: node-modules-
       - run: npm ci
       - run: npm run test --workspace=src/backend
 
@@ -50,25 +79,54 @@ jobs:
     runs-on: ubuntu-latest
     needs: lint
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0
         with:
           python-version: '3.11'
-          cache: pip
+      - uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4.0.2
+        with:
+          path: ~/.cache/pip
+          key: pip-${{ hashFiles('requirements.txt') }}
+          restore-keys: pip-
       - run: pip install -r requirements.txt
-      - run: python -m pytest src/ml/ --tb=short -q || true
-      - run: python -m flake8 src/ml/ --max-line-length=120 || true
-      - run: python -m mypy src/ml/ --ignore-missing-imports || true
+      - run: python -m pytest src/ml/ --tb=short -q --cov=src/ml --cov-report=xml --cov-fail-under=70
+      - run: python -m flake8 src/ml/ --max-line-length=120
+      - run: python -m mypy src/ml/ --ignore-missing-imports
+
+  security:
+    name: Security Scanning
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/setup-node@60ecd5dd1b667a8e52112f999ebc6e0c8267832c # v4.0.2
+        with:
+          node-version: 20
+      - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0
+        with:
+          python-version: '3.11'
+      - uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4.0.2
+        with:
+          path: node_modules
+          key: node-modules-${{ hashFiles('package-lock.json') }}
+          restore-keys: node-modules-
+      - run: npm ci
+      - run: npm audit --audit-level=moderate
+      - run: pip install pip-audit
+      - run: pip-audit -r requirements.txt
 
   build:
     name: Build
     runs-on: ubuntu-latest
-    needs: [test-frontend, test-backend, test-ml]
+    needs: [test-frontend, test-backend, test-ml, type-check, security]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/setup-node@60ecd5dd1b667a8e52112f999ebc6e0c8267832c # v4.0.2
         with:
           node-version: 20
-          cache: npm
+      - uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4.0.2
+        with:
+          path: node_modules
+          key: node-modules-${{ hashFiles('package-lock.json') }}
+          restore-keys: node-modules-
       - run: npm ci
       - run: npm run build

.pre-commit-config.yaml

@@ -0,0 +1,45 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+
+  - repo: https://github.com/psf/black
+    rev: 24.4.2
+    hooks:
+      - id: black
+        language_version: python3.11
+
+  - repo: https://github.com/pycqa/flake8
+    rev: 7.0.0
+    hooks:
+      - id: flake8
+        args: [--max-line-length=120]
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        args: [--ignore-missing-imports]
+        additional_dependencies: []
+
+  - repo: https://github.com/pre-commit/mirrors-eslint
+    rev: v8.57.0
+    hooks:
+      - id: eslint
+        files: \.(ts|tsx)$
+        types: [file]
+        additional_dependencies:
+          - eslint@8.57.0
+          - "@typescript-eslint/parser@7.0.0"
+          - "@typescript-eslint/eslint-plugin@7.0.0"
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v3.2.0
+    hooks:
+      - id: prettier
+        files: \.(ts|tsx|json|css)$
+        types: [file]

CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to WELLab
+
+## Development Setup
+
+1. Clone the repository and install dependencies:
+   ```bash
+   make install
+   ```
+2. Copy the environment file and fill in your values:
+   ```bash
+   cp .env.example .env
+   ```
+3. Install pre-commit hooks:
+   ```bash
+   pre-commit install
+   ```
+4. Start the development servers:
+   ```bash
+   make dev
+   ```
+
+## Branch Naming Conventions
+
+Use the following prefixes for branch names:
+
+- `feature/` -- New features (e.g., `feature/causal-inference-api`)
+- `fix/` -- Bug fixes (e.g., `fix/cognito-token-refresh`)
+- `docs/` -- Documentation changes (e.g., `docs/api-reference`)
+
+## Commit Message Format
+
+Follow the Conventional Commits specification:
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`
+
+Examples:
+- `feat(ml): add survival analysis endpoint`
+- `fix(frontend): correct pagination in publication list`
+- `docs(api): update authentication flow diagram`
+
+## Code Review Process
+
+1. Open a pull request against `develop` (or `main` for hotfixes).
+2. At least one approving review is required before merging.
+3. All CI checks must pass (lint, type-check, tests, security scan).
+4. Resolve all review comments before merging.
+5. Use squash merging to keep the commit history clean.
+
+## Testing Requirements
+
+- All new features must include tests.
+- Maintain a minimum of 70% code coverage for `src/ml/`.
+- Run the full test suite before opening a PR:
+  ```bash
+  make test
+  ```
+- Run linting and type checks:
+  ```bash
+  make lint
+  make type-check
+  ```
+
+## Ethics Review Requirements for ML Changes
+
+Any pull request that modifies code in `src/ml/` must include:
+
+1. A description of the data used and any potential biases.
+2. An assessment of fairness implications across demographic groups.
+3. Documentation of model limitations and failure modes.
+4. Approval from at least one team member with domain expertise in the relevant health/wellness area.
+
+These requirements exist to ensure that ML models deployed in health-adjacent contexts meet ethical standards and do not cause harm to vulnerable populations.