docs: provides instructions on running and configuring the demos. (#675)

Author: anthonydmays

lib/java/fullstack_demo/.env.development

@@ -0,0 +1,2 @@
+CLERK_PERISHABLE_KEY=perishable key from clerk
+CLERK_SECRET_KEY=secret key from clerk

lib/java/fullstack_demo/.env.development.redis

@@ -0,0 +1,5 @@
+CLERK_PERISHABLE_KEY=perishable key from clerk
+CLERK_SECRET_KEY=secret key from clerk
+REDIS_HOST=Redis database host (probably from upstash)
+REDIS_PORT=Redis database prt
+REDIS_PASSWORD=Redis database password

lib/java/fullstack_demo/README.md

@@ -0,0 +1,48 @@
+# Full-stack App Demo
+
+## Purpose
+
+This project demonstrates a fully working task management app built using React, TypeScript, and Java. The app is deployed live on Fly.io at https://fullstack-demo-cold-breeze-8913.fly.dev/.
+
+## Running the app
+
+To run the app, you'll first need to configure the Java web server. Copy the [.env.development](./.env.development) file to `.env` and set up the Clerk keys by setting up an account at https://clerk.dev. Once done, you can start the server using the following command
+
+```bash
+./gradlew bootRun
+```
+
+You can access the site at https://localhost:8080.
+
+If you want to test changes to the frontend client code, it would be easier to run the frontend react site separate. Navigate to [src/main/frontend](./src/main/frontend/) and run the React website as normal:
+
+```bash
+npm run dev
+```
+
+## Architecture
+
+The app is built using the React library running on a Java web server. The homepage is located at [src/main/frontend/src/App.tsx](./src/main/frontend/src/App.tsx) and contains the main `TodoApp` component.
+
+The `TodoApp` component and sub-components uses `fetch` to get data from the backend API which is located at [TodosController.java](./src/main/java/com/codedifferently/fullstack_demo/controller/TodosController.java).
+
+The backend API gets a repository instance from a bean configured at [RepositoryConfiguration.java](./src/main/java/com/codedifferently/fullstack_demo/repository/RepositoryConfiguration.java), using an environment variable to choose between a JSON repository implementation or a Redis version. For more on the repository pattern, [see this article on Medium](https://medium.com/@pererikbergman/repository-design-pattern-e28c0f3e4a30).
+
+## Connecting to Redis
+
+By default, the app is configured to store data an in-memory which gets cleared out as soon as the web server is shut down or restarts. You can connect it to a Redis database by creating one at Upstash or on Vercel (called Upstash KV). Then, uncomment the commented out lines in [application.yml](./src/main/resources/application.yml) and update your `.env` file.
+
+## Deploying live
+
+To deploy this app, sign up for an account on Fly.io and create a project pointing to your fork of this repo. You can run the `./gradlew build` to build the app and then use `fly deploy` utility command to deploy the Java web server to production. Fly.io leverages the [Dockerfile](./Dockerfile) config to run the web server.
+
+## Tools
+
+Here are a list of tools used to compile this demo. You can read the official documentation to learn how various aspects of the demo function.
+
+* React (https://react.dev)
+* Java Spring Boot (https://spring.io/projects/spring-boot)
+* Java Spring MVC (https://spring.io/guides/gs/serving-web-content)
+* Upstash Redis (https://upstash.com/docs/redis/overall/getstarted)
+* Fly.io (https://fly.io)
+* Docker (https://docs.docker.com/build/concepts/dockerfile/)

lib/java/fullstack_demo/src/main/frontend/package.json

@@ -4,10 +4,10 @@
   "version": "0.0.0",
   "type": "module",
   "scripts": {
-    "dev": "vite",
+    "dev": "NODE_ENV=development vite",
     "build": "tsc -b && NODE_ENV=production vite build",
     "lint": "eslint .",
-    "preview": "vite preview"
+    "preview": "NODE_ENV=production vite preview"
   },
   "dependencies": {
     "@clerk/clerk-react": "^5.17.1",

lib/typescript/fullstack_demo/.env.example

@@ -0,0 +1,3 @@
+NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=Your Next Public Clerk Publishable Key here
+CLERK_SECRET_KEY=Your Clerk Secret Key here
+DB_TYPE=in-memory

lib/typescript/fullstack_demo/.env.example.redis

@@ -0,0 +1,5 @@
+NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=Your Next Public Clerk Publishable Key here
+CLERK_SECRET_KEY=Your Clerk Secret Key here
+DB_TYPE=redis
+KV_REST_API_TOKEN=Your Redis api token here
+KV_REST_API_URL=Your Redis database URL

lib/typescript/fullstack_demo/.gitignore

@@ -31,6 +31,8 @@ yarn-error.log*
 
 # env files (can opt-in for committing if needed)
 .env*
+!.env.example
+!.env.example.*
 
 # vercel
 .vercel

lib/typescript/fullstack_demo/README.md

@@ -1,36 +1,41 @@
-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).
+# Full-stack App Demo
 
-## Getting Started
+## Purpose
 
-First, run the development server:
+This project demonstrates a fully working task management app built using NextJS and TypeScript. The app is deployed live on Vercel at https://code-differently-24-q4.vercel.app/
+
+## Running the app
+
+To run the app, copy the [.env.example](./.env.example) file as `.env` and setup the Clerk keys by setting up an account at https://clerk.dev. Once done, you can start up the local dev server with the following commands: 
 
 ```bash
+npm install
 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.
+## Architecture
+
+The app is built using the React library running on the NextJS framework. The homepage is located at [src/app/page.tsx](./src/app/page.tsx) and contains the main `TodoApp` component.
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+The `TodoApp` component and sub-components uses `fetch` to get data from the backend API which is located at [src/app/api/todos/route.ts](./src/app/api/todos/route.ts).
 
-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.
+The backend API gets a repository instance from [src/repositories/index.ts](./src/repositories/index.ts), using an environment variable to choose between a JSON repository implementation or a Redis version. For more on the repository pattern, [see this article on Medium](https://medium.com/@pererikbergman/repository-design-pattern-e28c0f3e4a30).
 
-## Learn More
+## Connecting to Redis
 
-To learn more about Next.js, take a look at the following resources:
+By default, the app is configured to store data on the web server in a JSON file (./src/repositories/db.json). You can connect it to a Redis database by creating one on Vercel (called Upstash KV). Then, set the `DB_TYPE` to `redis` in the `.env` file and configure the additional config keys listed in `.env.example.redis`.
 
-- [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.
+## Deploying live
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+To deploy this app, sign up for an account on Vercel and create a project pointing to your fork of this repo. You'll need to configure the environment variables you setup in your local `.env` file using the Vercel UI.
 
-## Deploy on Vercel
+## Tools
 
-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.
+Here are a list of tools used to compile this demo. You can read the official documentation to learn how various aspects of the demo function.
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+* NextJS (https://nextjs.org)
+* Vercel (https://vercel.com)
+* Clerk (https://clerk.dev)
+* React (https://react.dev)
+* LowDB (https://github.com/typicode/lowdb)
+* Upstash Redis (https://upstash.com/docs/redis/overall/getstarted)