Contribution guide

.example.env

@@ -0,0 +1,11 @@
+DATABASE_URL=postgres://user:password@localhost:5432/zotnfound
+NEXT_PUBLIC_MAPBOX_DARK_URL=your_map_api_key
+BETTER_AUTH_API_KEY=your_better_auth_api_key
+DRIZZLE_DATABASE_URL=postgres://user:password@localhost:5432/zotnfound
+GOOGLE_CLIENT_ID=your_google_client_id
+GOOGLE_CLIENT_SECRET=your_google_client_secret
+AWS_HOST=your-db-host
+AWS_USER=your-db-user
+AWS_PASSWORD=your-db-password
+AWS_DB_NAME=your-db-name
+AWS_PORT=5432

CONTRIBUTING.md

@@ -0,0 +1,12 @@
+# CONTRIBUTIONS
+
+We welcome contributions to this project! Whether you're fixing a bug, adding a new feature, or improving documentation, your help is appreciated. Please follow the guidelines below to ensure a smooth contribution process.
+
+## How to Contribute
+
+1. Follow the Git guidelines in [contributions/git.md](contributions/git.md).
+2. Follow our File Structure conventions in [contributions/conventions.md](contributions/conventions.md).
+3. Set up the development environment as described in [contributions/requirements.md](contributions/requirements.md).
+4. Make sure your database is set up correctly. See [contributions/database.md](contributions/database.md) for details.
+5. Contact us if you need any help or have questions.
+6. Thank you for contributing! 💖

contributions/conventions.md

@@ -0,0 +1,17 @@
+# Conventions
+
+The documentation of the following conventions we use, while using NextJS, TypeScript, and TailwindCSS.
+
+### Project Structure
+
+- **`/app`**: Contains the main application code, including pages and components.
+  - **`/api`**: API routes.
+  - **`/about`**: About page.
+  - **`/page.tsx`**: The main entry point of the application.
+- **`/components`**: Reusable UI components / Small Composable pieces. `/ui` for generic UI components or ShadCN components.
+- **`/lib`**: Utility functions and constants.
+- **`/db`**: Database-related code, schema for things like auth and our data.
+- **`/server`**: Server-side code, make sure to `import "server-only";` at the top of files here, since this runs on the server only and performs actions like DB queries.
+  - **`/actions`**: Server actions that can be called from the client. General `/create`, `/update`, `/delete` actions for the data model / table we want.
+  - **`/data`**: Data fetching functions.
+- **`/hooks`**: Custom React hooks.

contributions/database.md

@@ -0,0 +1,33 @@
+# Database
+
+After Connecting your AWS EC2 Instance, you will need to set up the database schema. We use Drizzle ORM for database migrations and schema management.
+
+## Setting Up the Database
+
+1. **Install Dependencies**: Ensure you have all necessary dependencies installed. If you haven't done so, run:
+   ```bash
+   bun install
+   ```
+   or
+   ```bash
+   npm install
+   ```
+2. **Run Migrations**: To set up the database schema, run the following commands:
+   ```bash
+   bunx drizzle-kit generate
+   bunx drizzle-kit migrate
+   ```
+   or
+   ```bash
+   npx drizzle-kit generate
+   npx drizzle-kit migrate
+   ```
+   This will create the necessary tables and structures in your PostgreSQL database as defined in the migration files.
+3. **Verify the Setup**: After running the migrations, you can verify that the tables have been created by connecting to your PostgreSQL database. You can explore the database in Drizzle Studio by running the following command:
+
+```
+npx drizzle-kit studio
+```
+
+The database should be ready with the required schema for ZotNFoundClone. You can now proceed with running the application and testing its functionality.
+Keep in mind, there is no data in the database yet, you will need to add data directly into the database.

contributions/git.md

@@ -0,0 +1,49 @@
+# Git
+
+This is our approach to Git.
+
+### How to Contribute
+
+1. **Fork the Repository**: Start by forking the repository to your own GitHub account.
+2. **Clone the Fork**: Clone your forked repository to your local machine using:
+   ```bash
+   git clone
+   cd <your-forked-repo>
+   ```
+3. **Create a Branch**: Create a new branch for your feature or bug fix:
+   ```bash
+   git checkout -b feature-or-bugfix-name
+   ```
+
+(The Github CLI streamlines this process with `gh repo fork` and `gh repo clone` commands! We recommend using it. Check out [GitHub CLI](https://cli.github.com/) for more details.)
+
+4. **Make Changes**: Make your changes in the codebase. Ensure your code follows the project's coding style (Prettier) and conventions(ESLint). Specifically, before each commit, run the following commands:
+
+```
+npm lint
+npm format
+```
+
+5. **Test Your Changes**: Please run exhaustive tests before committing your code.
+6. **Commit Your Changes**: Commit your changes with a clear and descriptive commit message:
+
+   ```bash
+   git add .
+   git commit -m <conventional-commit>
+   ```
+
+   We follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages. Here are some examples:
+   - `feat: add new feature`
+   - `fix: fix a bug`
+   - `docs: update documentation`
+   - `style: improve code formatting`
+   - `refactor: refactor code without changing functionality`
+
+7. **Push Your Changes**: Push your changes to your forked repository:
+   ```bash
+   git push origin feature-or-bugfix-name
+   ```
+8. **Create a Pull Request**: Go to the original repository and create a pull request from your forked repository. Provide a clear description of your changes and reference any related issues.
+9. **Address Feedback**: Be responsive to any feedback or requests for changes from the project maintainers. Make necessary updates and push them to your branch.
+
+Once again! Thank you for considering contributing to this project. Your efforts help make it better for everyone! If you have any questions or need assistance, feel free to reach out to the project maintainers.

contributions/requirements.md

@@ -0,0 +1,76 @@
+# Requirements for ZotNFoundClone
+
+These are the requirements to run and develop ZotNFound:
+
+### Development Environment
+
+- **Bun** (preferred) or **Node.js** (>=20.x)
+  - Bun can run Next.js projects and is compatible with most npm packages.
+  - If using Node.js, ensure you have npm or yarn installed.
+- **Next.js** (15.3.1-canary.15)
+- **TypeScript** (>=5.8.3)
+- **PostgreSQL** (for local development, required by `pg` and `drizzle-orm`)
+- **TailwindCSS** (>=4)
+- **Prettier** (>=3.6.2)
+- **ESLint** (>=9)
+- **dotenv** (for environment variable management)
+
+### API Keys & Environment Variables
+
+Create a `.env.local` file in the project root with the following (example names, adjust as needed):
+
+```env
+DATABASE_URL=postgres://user:password@localhost:5432/zotnfound
+NEXT_PUBLIC_MAPBOX_DARK_URL=your_map_api_key
+BETTER_AUTH_API_KEY=your_better_auth_api_key
+DRIZZLE_DATABASE_URL=postgres://user:password@localhost:5432/zotnfound
+GOOGLE_CLIENT_ID=your_google_client_id
+GOOGLE_CLIENT_SECRET=your_google_client_secret
+AWS_HOST=your-db-host
+AWS_USER=your-db-user
+AWS_PASSWORD=your-db-password
+AWS_DB_NAME=your-db-name
+AWS_PORT=5432
+```
+
+- **DATABASE_URL**: PostgreSQL connection string.
+- **BETTER_AUTH_API_KEY**: Used for authentication. Found at [BetterAuth](https://www.better-auth.com/docs/installation).
+- **NEXT_PUBLIC_MAPBOX_DARK_URL**: For map services (Leaflet, etc). Please request from the project maintainer if you don't have one! Generally speaking you can make a public key [here](https://account.mapbox.com/access-tokens/). [Docs](https://docs.mapbox.com/help/dive-deeper/access-tokens/)
+- **DRIZZLE_DATABASE_URL**: For Drizzle ORM migrations.
+- **GOOGLE_CLIENT_ID** and **GOOGLE_CLIENT_SECRET**: For Google OAuth authentication. Set up a project in the [Google Developer Console](https://console.developers.google.com/). (We might just swap to the UCI Shared Auth provider in the future)
+- - **AWS_USER**, **AWS_PASSWORD**, **AWS_HOST**, **AWS_PORT**, **AWS_DB_NAME**: We are connecting to a PostgreSQL database hosted on AWS, you will need to set these environment variables for authentication. You can obtain these credentials from your AWS Console under the RDS or EC2 dashboard. For more information on retrieving database credentials, see the [AWS EC2 documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-connect-to-db.html).
+
+### Other Notes
+
+- Run `bun install` (or `npm install`) to install dependencies.
+- Use `bun run dev` (or `npm run dev`) to start the development server.
+- For formatting and linting, use `bun run format` and `bun run lint`.
+- For type checking, use `bun run type-check`.
+
+### AWS Configuration
+
+- Resource: [AWS CLI Docs](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)
+
+1.  Install the AWS CLI ([Download Link](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)) for your OS
+2.  Go to your terminal or powershell and run the command below to confirm that you have installed the CLI
+
+```
+aws --version
+```
+
+3. Run:
+
+```
+aws configure
+```
+
+It should produce output in this format:
+
+```
+AWS Access Key ID [None]: [paste your AWS Access Key]
+AWS Secret Key ID [None]: [paste your AWS Secret Key]
+Default region name [None]: [just hit enter]
+Default output format [None]: [just hit enter]
+```
+
+4. AWS CLI is configured

package.json

@@ -13,42 +13,42 @@
     "format:check": "prettier --check ."
   },
   "dependencies": {
-    "@radix-ui/react-dialog": "^1.1.6",
-    "@radix-ui/react-slot": "^1.1.2",
-    "@types/leaflet": "^1.9.16",
-    "@types/leaflet.markercluster": "^1.5.5",
-    "babel-plugin-react-compiler": "^19.0.0-beta-bafa41b-20250307",
-    "better-auth": "^1.2.8",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-slot": "^1.2.3",
+    "@types/leaflet": "^1.9.20",
+    "@types/leaflet.markercluster": "^1.5.6",
+    "babel-plugin-react-compiler": "^19.0.0-beta-ebf51a3-20250411",
+    "better-auth": "^1.3.14",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "dotenv": "^16.5.0",
+    "dotenv": "^16.6.1",
     "drizzle-orm": "^0.41.0",
     "leaflet": "^1.9.4",
     "lucide-react": "^0.482.0",
     "next": "15.3.1-canary.15",
-    "pg": "^8.14.1",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
+    "pg": "^8.16.3",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
     "react-leaflet": "^5.0.0",
     "react-leaflet-cluster-4-next": "^2.1.2",
     "server-only": "^0.0.1",
     "sst": "3.13.10",
-    "tailwind-merge": "^3.0.2",
+    "tailwind-merge": "^3.3.1",
     "tailwindcss-animate": "^1.0.7"
   },
   "devDependencies": {
-    "@eslint/eslintrc": "^3",
-    "@tailwindcss/postcss": "^4",
-    "@types/node": "^20",
-    "@types/pg": "^8.11.12",
-    "@types/react": "^19",
-    "@types/react-dom": "^19",
+    "@eslint/eslintrc": "^3.3.1",
+    "@tailwindcss/postcss": "^4.1.13",
+    "@types/node": "^20.19.17",
+    "@types/pg": "^8.15.5",
+    "@types/react": "^19.1.13",
+    "@types/react-dom": "^19.1.9",
     "drizzle-kit": "^0.30.6",
-    "eslint": "^9",
+    "eslint": "^9.36.0",
     "eslint-config-next": "15.2.0",
     "prettier": "^3.6.2",
-    "tailwindcss": "^4",
+    "tailwindcss": "^4.1.13",
     "ts-node": "^10.9.2",
-    "typescript": "^5.8.3"
+    "typescript": "^5.9.2"
   }
 }