refactor: move docs to apps & top-level clean-up

.github/workflows/ci.yml

@@ -5,13 +5,13 @@ on:
     paths-ignore:
       - 'deployment/**'
       - 'docker/**'
-      - 'docs/**'
+      - 'apps/docs/**'
   pull_request:
     branches: [main]
     paths-ignore:
       - 'deployment/**'
       - 'docker/**'
-      - 'docs/**'
+      - 'apps/docs/**'
 
 permissions:
   contents: read

.github/workflows/docs.yml

@@ -4,7 +4,8 @@ on:
   push:
     branches: [main]
     paths:
-      - 'docs/**'
+      - 'apps/docs/**'
+      - 'packages/common/src/contracts/**'
 
 permissions:
   contents: write
@@ -32,14 +33,15 @@ jobs:
         run: pnpm install
 
       - name: Docs - build
-        run: pnpm docs:build
+        working-directory: apps/docs
+        run: pnpm build
 
       - name: Set CNAME
-        run: echo "docs.intake24.org" > docs/.vitepress/dist/CNAME
+        run: echo "docs.intake24.org" > apps/docs/.vitepress/dist/CNAME
 
       - name: Deploy 🚀
         uses: JamesIves/github-pages-deploy-action@v4
         with:
           branch: ghp-docs
-          folder: docs/.vitepress/dist
+          folder: apps/docs/.vitepress/dist
           clean: true

docs/.vitepress/config.ts → apps/docs/.vitepress/config.ts

@@ -1,6 +1,6 @@
 import { defineConfig } from 'vitepress';
 
-import { description } from '../../package.json';
+import { description } from '../package.json';
 import { nav } from './nav';
 import { sidebar } from './sidebar';
 

docs/overview/source-code.md → apps/docs/overview/source-code.md

@@ -20,12 +20,12 @@ Deployable applications are in `apps` folder. Shared components are in `packages
 ├─ apps -> Applications
 │  ├─ api -> API Server
 │  ├─ admin -> Admin tool
+│  ├─ docs -> Documentation
 │  ├─ cli -> Command line interface
 │  ├─ portal -> Portal website
 │  └─ survey -> Survey application
 ├─ deployment - Ansible playbooks / scripts for deployment
 ├─ docker - Docker files for development
-├─ docs -> Documentation
 └─ packages
    ├─ api-client-v3 -> API Client (Intake24 V3)
    ├─ api-client-v4 -> API Client (Intake24 V4 - current)

apps/docs/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@intake24/docs",
+  "type": "module",
+  "version": "2024.8",
+  "private": true,
+  "description": "Intake24 documentation",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MRC-Epid-it24/intake24.git",
+    "directory": "apps/docs"
+  },
+  "scripts": {
+    "dev": "pnpm open-api && vitepress dev",
+    "build": "pnpm open-api && vitepress build",
+    "serve": "pnpm open-api && vitepress serve",
+    "open-api": "pnpm tsx scripts/open-api.ts"
+  },
+  "devDependencies": {
+    "@ts-rest/open-api": "^3.51.0",
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2",
+    "vitepress": "^1.5.0"
+  }
+}

apps/docs/scripts/open-api.ts

@@ -0,0 +1,160 @@
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { generateOpenApi } from '@ts-rest/open-api';
+
+import contract from '@intake24/common/contracts';
+
+import pkg from '../package.json';
+
+const defaultRecall = {
+  type: 'object',
+  properties: {
+    preMeals: { type: 'array', items: [] },
+    meals: { type: 'object', properties: {
+      preFoods: { type: 'array', items: [] },
+      foods: { type: 'array', items: [] },
+      postFoods: { type: 'array', items: [] },
+    } },
+    postMeals: { type: 'array', items: [] },
+    submission: { type: 'array', items: [] },
+  },
+};
+
+async function main() {
+  const document = generateOpenApi(contract, {
+    info: {
+      title: 'Intake24 API Reference',
+      description: pkg.description,
+      license: {
+        name: pkg.license,
+        url: 'https://opensource.org/license/apache-2-0',
+      },
+      version: pkg.version,
+    },
+    servers: [
+      {
+        url: 'https://api.example.com',
+        description: 'Intake24 API instance',
+      },
+    ],
+    components: {
+      securitySchemes: {
+        bearerHttpAuthentication: {
+          description: 'Bearer token using a JWT',
+          type: 'http',
+          scheme: 'Bearer',
+          bearerFormat: 'JWT',
+        },
+      },
+    },
+  }, {
+    operationMapper: (operation, appRoute) => {
+      /*
+      * !!! TEMP HACKY REMOVAL OF HUGE RECALL SURVEY SCHEME OPEN API JSON SCHEME !!!
+      * - size of the open-api json file grows from ~15MB to ~150MB, which is due to survey scheme recall JSON schema
+      * - TODO: figure out how to maybe use JSON $refs with @ts-rest/open-api ?
+      */
+      if (appRoute.path === '/surveys/:slug/parameters') {
+        operation.responses['200'].content['application/json'].schema.properties.surveyScheme.properties.prompts = { ...defaultRecall };
+        return operation;
+      }
+
+      if (
+        appRoute.path === '/admin/survey-schemes'
+        || appRoute.path === '/admin/survey-schemes/:surveySchemeId'
+        || appRoute.path === '/admin/survey-schemes/:surveySchemeId/edit'
+        || appRoute.path === '/admin/survey-schemes/:surveySchemeId/copy'
+        || appRoute.path === '/admin/survey-schemes/:surveySchemeId/templates'
+      ) {
+        if (operation.requestBody?.content['application/json']?.schema?.properties?.prompts)
+          operation.requestBody.content['application/json'].schema.properties.prompts = { ...defaultRecall };
+
+        if (operation.responses['200']?.content['application/json'].schema?.properties?.data)
+          operation.responses['200'].content['application/json'].schema.properties.data = { type: 'array' };
+        if (operation.responses['200']?.content['application/json'].schema?.properties?.prompts)
+          operation.responses['200'].content['application/json'].schema.properties.prompts = { ...defaultRecall };
+        if (operation.responses['201']?.content['application/json'].schema?.properties?.prompts)
+          operation.responses['201'].content['application/json'].schema.properties.prompts = { ...defaultRecall };
+
+        return operation;
+      }
+
+      if (
+        appRoute.path === '/admin/survey-scheme-prompts'
+        || appRoute.path === '/admin/survey-scheme-prompts/:surveySchemePromptId'
+        || appRoute.path === '/admin/survey-scheme-prompts/:surveySchemePromptId/edit'
+        || appRoute.path === '/admin/survey-scheme-prompts/:surveySchemePromptId/sync'
+      ) {
+        if (operation.requestBody?.content['application/json']?.schema?.properties?.prompt)
+          operation.requestBody.content['application/json'].schema.properties.prompt = { type: 'object' };
+
+        if (operation.responses['200']?.content['application/json'].schema?.properties?.data)
+          operation.responses['200'].content['application/json'].schema.properties.data = { type: 'array' };
+        if (operation.responses['200']?.content['application/json'].schema?.properties?.prompt)
+          operation.responses['200'].content['application/json'].schema.properties.prompt = { type: 'object' };
+        if (operation.responses['201']?.content['application/json'].schema?.properties?.prompt)
+          operation.responses['201'].content['application/json'].schema.properties.prompt = { type: 'object' };
+
+        return operation;
+      }
+
+      if (
+        appRoute.path === '/admin/surveys'
+        || appRoute.path === '/admin/surveys/:surveyId'
+        || appRoute.path === '/admin/surveys/:surveyId/edit'
+      ) {
+        if (operation.requestBody?.content['application/json']?.schema?.properties?.surveySchemeOverrides?.properties?.prompts)
+          operation.requestBody.content['application/json'].schema.properties.surveySchemeOverrides.properties.prompts = { type: 'array' };
+
+        if (operation.responses['200']?.content['application/json'].schema?.properties?.surveySchemeOverrides?.properties?.prompts)
+          operation.responses['200'].content['application/json'].schema.properties.surveySchemeOverrides.properties.prompts = { type: 'array' };
+        if (operation.responses['201']?.content['application/json'].schema?.properties?.surveySchemeOverrides?.properties?.prompts)
+          operation.responses['201'].content['application/json'].schema.properties.surveySchemeOverrides.properties.prompts = { type: 'array' };
+
+        if (operation.responses['200']?.content['application/json'].schema?.properties?.surveyScheme?.properties?.prompts)
+          operation.responses['200'].content['application/json'].schema.properties.surveyScheme.properties.prompts = { ...defaultRecall };
+        if (operation.responses['201']?.content['application/json'].schema?.properties?.surveyScheme?.properties?.prompts)
+          operation.responses['201'].content['application/json'].schema.properties.surveyScheme.properties.prompts = { ...defaultRecall };
+
+        return operation;
+      }
+
+      if (appRoute.path === '/admin/survey-schemes/refs') {
+        if (operation.responses['200']?.content['application/json'].schema?.properties?.templates)
+          operation.responses['200'].content['application/json'].schema.properties.templates = { type: 'array' };
+
+        return operation;
+      }
+
+      if (appRoute.path === '/admin/survey-scheme-prompts/refs') {
+        if (operation.responses['200']?.content['application/json'].schema?.properties?.schemes)
+          operation.responses['200'].content['application/json'].schema.properties.schemes = { type: 'array' };
+
+        return operation;
+      }
+
+      if (appRoute.path === '/admin/references/survey-schemes') {
+        if (operation.responses['200']?.content['application/json'].schema?.properties?.data)
+          operation.responses['200'].content['application/json'].schema.properties.data = { type: 'array' };
+
+        return operation;
+      }
+
+      return operation;
+    },
+  });
+
+  writeFileSync(
+    resolve('public', 'open-api.json'),
+    JSON.stringify(document, null, 2),
+    'utf8',
+  );
+}
+
+main().catch((err) => {
+  console.error(err);
+
+  process.exitCode = process.exitCode ?? 1;
+  process.exit();
+});

apps/docs/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@intake24/common/*": ["../../packages/common/src/*"]
+    }
+  }
+}

package.json

@@ -33,10 +33,6 @@
     "db:system:migrate:undo": "pnpm --filter @intake24/db db:system:migrate:undo",
     "cli": "pnpm --filter @intake24/cli cli",
     "i18n:sync": "pnpm --filter @intake24/i18n i18n:sync",
-    "docs:dev": "pnpm docs:open-api && vitepress dev docs",
-    "docs:build": "pnpm docs:open-api && vitepress build docs",
-    "docs:serve": "pnpm docs:open-api && vitepress serve docs",
-    "docs:open-api": "pnpm tsx scripts/open-api.ts",
     "changelog": "conventional-changelog -p angular",
     "release": "pnpm tsx scripts/release.ts",
     "lint": "eslint . --fix",
@@ -50,7 +46,6 @@
   },
   "devDependencies": {
     "@antfu/eslint-config": "^3.12.1",
-    "@ts-rest/open-api": "^3.51.0",
     "@types/node": "^22.10.2",
     "@types/prompts": "^2.4.9",
     "calver": "^24.1.0",
@@ -65,9 +60,7 @@
     "rimraf": "^6.0.1",
     "simple-git-hooks": "^2.11.1",
     "tsx": "^4.19.2",
-    "typescript": "^5.7.2",
-    "vite": "^6.0.5",
-    "vitepress": "^1.5.0"
+    "typescript": "^5.7.2"
   },
   "simple-git-hooks": {
     "pre-commit": "pnpm lint-staged",