README updates and add issue template

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,76 @@
+## Issue Description
+
+<!-- Provide a clear and concise description of the issue you're experiencing -->
+
+## Sample App Information
+
+**Which sample app are you using?**
+<!-- Check one -->
+- [ ] Java (Spring Boot)
+- [ ] JavaScript (Express.js)
+- [ ] Python (FastAPI)
+
+## Environment Details
+
+**MongoDB Database Version:**
+<!-- e.g., 7.0, 8.0, etc. -->
+
+**MongoDB Driver Version:**
+<!-- e.g., Java Driver 5.2.0, Node.js Driver 6.10.0, PyMongo 4.10.1, etc. -->
+
+**Deployment Type:**
+<!-- Check one -->
+- [ ] Local MongoDB instance
+- [ ] MongoDB Atlas (cloud)
+- [ ] Docker container
+- [ ] Other (please specify):
+
+**Operating System:**
+<!-- e.g., macOS 14.5, Ubuntu 22.04, Windows 11, etc. -->
+
+**Runtime Version:**
+<!-- e.g., Java 17, Node.js 20.11.0, Python 3.11, etc. -->
+
+## Steps to Reproduce
+
+<!-- Provide detailed steps to reproduce the issue -->
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+<!-- What did you expect to happen? -->
+
+## Actual Behavior
+
+<!-- What actually happened? -->
+
+## Error Messages or Logs
+
+<!-- If applicable, paste any error messages or relevant log output -->
+
+```
+<!-- Paste error messages or logs here -->
+```
+
+## Additional Context
+
+<!-- Add any other context about the problem here, such as:
+- Screenshots
+- Configuration files
+- Network setup
+- Any modifications you made to the sample app
+- Links to relevant documentation
+-->
+
+## Checklist
+
+Before submitting this issue, please confirm:
+
+- [ ] I have checked the README for setup instructions
+- [ ] I have verified my MongoDB connection string is correct
+- [ ] I have installed all required dependencies
+- [ ] I have searched existing issues to avoid duplicates
+

README.md

@@ -1,3 +1,111 @@
 # Docs Sample Apps
 
-A repository of sample applications for the MongoDB documentation.
+A repository of sample applications for the MongoDB documentation. This README
+describes internal details for the repository maintainers. If you are a developer
+having issues with the sample app, please refer to the `Issues` section below.
+
+## Sample Apps
+
+This repository currently contains a single sample app using the `mflix` dataset.
+
+### MFlix Sample App
+
+The sample app provides a Next.js frontend in the `client` directory, with the
+choice of three backend stacks in the `server` directory:
+
+- Java: Spring Boot
+- JavaScript: Express.js
+- Python: FastAPI
+
+```
+├── mflix/
+│   ├── client/               # Next.js frontend - source for all `mflix` sample app backend repos
+│   └── server/
+│       ├── express/          # Express.js backend - source for sample-app-nodejs-mflix
+│       ├── java-spring/      # Java/Spring backend - source for sample-app-java-mflix
+│       └── python/           # Python/FastAPI backend - source for sample-app-python-mflix
+├── README.md
+├── copier-config.yaml
+└── deprecated_examples.json
+```
+
+## Artifact Repositories
+
+This repository serves as the source for the following artifact repositories:
+
+- Java: [mongodb/sample-app-java-mflix](https://github.com/mongodb/sample-app-java-mflix)
+- JavaScript: [mongodb/sample-app-nodejs-mflix](https://github.com/mongodb/sample-app-nodejs-mflix)
+- Python: [mongodb/sample-app-python-mflix](https://github.com/mongodb/sample-app-python-mflix)
+
+## Development
+
+When you merge to `main`, a copier tool copies the source from this repository
+to a target repository for each sample app. For configuration details, refer to
+`copier-config.yaml`.
+
+### Branching Model
+
+For development, work from the `development` branch. Make incremental PRs
+containing new features and bug fixes to `development`, *not* `main`.
+
+When all development work is complete, *then* create a release PR from
+`development` to `main`. Upon merging to `main,` the copier tool runs
+automatically. It creates a new PR in the target repository, which must be
+tested and merged manually.
+
+### Deleting Files
+
+If a PR from `development` to `main` deletes any files, this creates a new
+entry in the `deprecated_examples.json` file. This entry resembles:
+
+```json
+{
+  "filename": "go/gcloud24march_v2.go",
+  "repo": "docs-code-examples-test-target",
+  "branch": "v2.2",
+  "deleted_on": "2025-03-24T18:16:30Z"
+},
+```
+
+The copier tool does not delete files from the target repository. You must
+manually delete files from the target repository that are listed in
+`deprecated_examples.json`. This is an intentional step to avoid accidentally
+deleting files that are referred to in documentation. Review documentation
+references before deleting files.
+
+## Release Process
+
+When you merge a release PR from `development` to `main`, the copier tool
+creates a new PR in the target repository. This PR must be tested and merged
+manually. This is an intentional design choice to ensure:
+
+- The sample app still functions as expected after copying.
+- Any documentation references are updated as part of the release process.
+
+To test and verify the PR, navigate to the target repository - see
+`Artifact Repositories` above. Perform the following checks:
+
+- [ ] Verify that the PR contains the expected changes.
+- [ ] Check out the PR locally.
+  - [ ] Build and test the changes.
+  - [ ] Run the tests
+  - [ ] Run the application and verify that it functions as expected.
+- [ ] Review the `deprecated_examples.json` file for any files that need to be
+  deleted. If files are deleted:
+  - [ ] Add a commit to the copier PR to delete the files from the target repository.
+- [ ] Merge the PR.
+
+## Issues
+
+If you are a developer having issues with the sample app, feel free to open an
+issue in this repository. Please include the following information:
+
+- [ ] The sample app you are using (Java, JavaScript, or Python)
+- [ ] The version of the MongoDB database you are using
+- [ ] The version of the MongoDB driver you are using
+- [ ] What type of deployment you're using (local, Atlas, etc.)
+- [ ] Any other relevant information that might help us reproduce the issue
+
+## Contributions
+
+We are not currently accepting public contributions to this repository.

mflix/README-JAVA-SPRING.md

@@ -0,0 +1,26 @@
+# Java Spring Boot MongoDB Sample MFlix Application
+
+[TODO: Add intro]
+
+```
+├── README.md
+├── client/     # Next.js frontend
+└── server/     # Java Spring backend
+```
+
+## Getting Started
+
+[TODO: Add getting started instructions explaining how to set connection string, start server, start client, etc.]
+
+## Issues
+
+If you have problems running the sample app, please check the following:
+
+- [ ] Verify that you have set your MongoDB connection string in the `.env` file.
+- [ ] Verify that you have started the Java Spring server.
+- [ ] Verify that you have started the Next.js client.
+- [ ] Verify that you have no firewalls blocking access to the server or client ports.
+
+If you have verified the above and still have issues, please
+[open an issue](https://github.com/mongodb/docs-sample-apps/issues/new/choose)
+on the source repository `mongodb/docs-sample-apps`.

mflix/README-JAVASCRIPT-EXPRESS.md

@@ -0,0 +1,26 @@
+# JavaScript Express.js MongoDB Sample MFlix Application
+
+[TODO: Add intro]
+
+```
+├── README.md
+├── client/     # Next.js frontend
+└── server/     # Express.js backend
+```
+
+## Getting Started
+
+[TODO: Add getting started instructions explaining how to set connection string, start server, start client, etc.]
+
+## Issues
+
+If you have problems running the sample app, please check the following:
+
+- [ ] Verify that you have set your MongoDB connection string in the `.env` file.
+- [ ] Verify that you have started the Express server.
+- [ ] Verify that you have started the Next.js client.
+- [ ] Verify that you have no firewalls blocking access to the server or client ports.
+
+If you have verified the above and still have issues, please
+[open an issue](https://github.com/mongodb/docs-sample-apps/issues/new/choose)
+on the source repository `mongodb/docs-sample-apps`.

mflix/README-PYTHON-FASTAPI.md

@@ -0,0 +1,26 @@
+# Python FastAPI MongoDB Sample MFlix Application
+
+[TODO: Add intro]
+
+```
+├── README.md
+├── client/     # Next.js frontend
+└── server/     # Python FastAPI backend
+```
+
+## Getting Started
+
+[TODO: Add getting started instructions explaining how to set connection string, start server, start client, etc.]
+
+## Issues
+
+If you have problems running the sample app, please check the following:
+
+- [ ] Verify that you have set your MongoDB connection string in the `.env` file.
+- [ ] Verify that you have started the Python FastAPI server.
+- [ ] Verify that you have started the Next.js client.
+- [ ] Verify that you have no firewalls blocking access to the server or client ports.
+
+If you have verified the above and still have issues, please
+[open an issue](https://github.com/mongodb/docs-sample-apps/issues/new/choose)
+on the source repository `mongodb/docs-sample-apps`.