doc: coding conventions and proposal submissions (#250)

* doc: coding conventions and proposal submissions

* doc: add code standards to TOC

* make coding_contention.md path relative in contributor guidelines

README.md

@@ -139,6 +139,7 @@ For discussion and suggestion you can join us: **[community discord server](http
   * [Code of Conduct](documents/contributions/code_of_conduct.md)
   * [Contributor Guidelines](documents/contributions/contributor_guidelines.md)
   * [Documentation Guidelines](documents/contributions/documentation_guidelines.md)
+  * [Code Standards and Conventions](documents/contributions/coding_conventions.md)
   * [Testing](documents/contributions/testing.md)
   * [Pull Request Template](documents/contributions/pull_request_template.md)
   * [Contributors](CONTRIBUTORS.md)

documents/contributions/coding_conventions.md

@@ -0,0 +1,104 @@
+# Coding Conventions
+
+## Node.js API Server
+
+### 1. General Guidelines
+
+- Follow the [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript) for general JavaScript coding conventions.
+- Use "clean code" principles, such as keeping functions and modules small, adhering to the single responsibility principle, and writing expressive and readable code.
+- Use meaningful and descriptive variable and function names.
+- Prioritize code readability and maintainability over brevity.
+- Use the provided .eslintrc and .prettierrc files for consistent code formatting.
+- Use CommonJS modules (require/exports) for Node.js modules.
+- Organize and modularize the codebase using separate files for different concerns.   
+
+### 2. API Design
+
+- Follow RESTful principles when designing APIs.
+- Use meaningful and descriptive names for routes, controllers, services, and models.
+- Use appropriate HTTP methods (GET, POST, PUT, DELETE) for each route.
+- Use proper status codes and response structures for consistent API responses (ie. 2xx for success, 4xx for bad request from client, 5xx for server error, etc.).
+- Use try-catch blocks to catch and handle exceptions gracefully.
+- Implement proper error handling and consistently return appropriate error responses.
+- Use the logging system included in the `utils` directory to log important events and errors. 
+- Do JWT-based, stateless authentication using the `requireJWTAuth` middleware.
+
+### 3. File Structure
+
+*Note: The API is undergoing a refactor to separate out the code for improved separation of concerns, testability, and maintainability. Any new APIs must follow the structure using the auth system as an example, which separates out the routes, controllers, services, and models into separate files.*
+
+#### Routes
+
+Specifies each http request method, any middleware to be used, and the controller function to be called for each route.
+
+- Define routes using the Express Router in separate files for each resource or logical grouping.
+- Use descriptive route names and adhere to RESTful conventions.
+- Keep routes concise and focused on a single responsibility.
+- Prefix all routes with the /api namespace.
+  
+#### Controllers
+
+Contains the logic for each route, including calling the appropriate service functions and returning the appropriate response status code and JSON body.
+
+- Create a separate controller file for each route to handle the request/response logic.
+- Name controller files using the PascalCase convention and append "Controller" to the file name (e.g., UserController.js).
+- Use controller methods to encapsulate logic related to the route handling.
+- eep controllers thin by delegating complex operations to service or model files.
+
+#### Services
+
+Contains complex business logic or operations shared across multiple controllers.
+
+- Name service files using the PascalCase convention and append "Service" to the file name (e.g., AuthService.js).
+- Avoid tightly coupling services to specific models or databases for better reusability.
+- Maintain a single responsibility principle within each service.
+  
+#### Models
+
+Defines Mongoose models to represent data entities and their relationships.
+
+- Use singular, PascalCase names for model files and their associated collections (e.g., User.js and users collection).
+- Include only the necessary fields, indexes, and validations in the models.
+- Keep models independent of the API layer by avoiding direct references to request/response objects.
+
+### 4. Database Access (MongoDB and Mongoose)
+
+- Use Mongoose (https://mongoosejs.com) as the MongoDB ODM.
+- Create separate model files for each entity and ensure clear separation of concerns.
+- Use Mongoose schema validation to enforce data integrity.
+- Handle database connections efficiently and avoid connection leaks.
+- Use Mongoose query builders to create concise and readable database queries.
+
+### 5. Testing and Documentation
+
+*Note: the repo currently lacks sufficient automated unit and integration tests for both the client and the API. This is a great first issue for new contributors wanting to familiarize with the codebase.*
+
+- Write unit tests for all critical and complex functionalities using Jest.
+- Write integration tests for all API endpoints using Supertest.
+- Write end-to-end tests for all client-side functionalities using Playwright.
+- Use descriptive test case and function names to clearly express the test's purpose.
+- Document the code using JSDoc comments to provide clear explanations of functions, parameters, and return types. (WIP)
+
+
+## React Client
+
+### General TypeScript and React Best Practices
+
+- Use [TypeScript best practices](https://onesignal.com/blog/effective-typescript-for-react-applications/) to benefit from static typing and improved tooling.
+- Group related files together within folders.
+- Name components using the PascalCase convention.
+- Use concise and descriptive names that accurately reflect the component's purpose.
+- Split complex components into smaller, reusable ones when appropriate.
+- Keep the rendering logic within components minimal.
+- Extract reusable parts into separate functions or hooks.
+- Apply prop type definitions using TypeScript types or interfaces.
+- Use form validation where appropriate. (note: we use [React Hook Form](https://react-hook-form.com/) for form validation and submission)
+
+### Data Services
+
+Use the conventions found in the `data-provider` directory for handling data services. For more information, see [this article](https://www.danorlandoblog.com/chatgpt-clone-data-services-with-react-query/) which describes the methodology used.
+
+### State Management
+
+Use [Recoil](https://recoiljs.org/) for state management, but *DO NOT pollute the global state with unnecessary data*. Instead, use local state or props for data that is only used within a component or passed down from parent to child.
+  

documents/contributions/contributor_guidelines.md

@@ -5,11 +5,19 @@ such as bug reports, documentation improvements, feature requests, and code cont
 
 ## Contributing Guidelines
 
-When contributing to this repository, please first discuss the change you wish to make via [issue](https://github.com/danny-avila/chatgpt-clone/issues) or 
-join our discord [Discord community](https://discord.gg/NGaa9RPCft).
+If the feature you would like to contribute has not already received prior approval from the project maintainers (ie. the feature is currently on the roadmap or on the [trello board]()), please submit a proposal in the [proposals category](https://github.com/danny-avila/chatgpt-clone/discussions/categories/proposals) of the discussions board before beginning work on it. 
+- Proposals should include specific implementation details including areas of the application that will be effected by the change inlcuding designs if applicable, and any other relevant information that might be required for a speedy review.
+- Proposals are not required for small changes, bug fixes, or documentation improvements. 
+- Small changes and bug fixes should be tied to an [issue](https://github.com/danny-avila/chatgpt-clone/issues) and included in the corresponding pull request for tracking purposes. 
+ 
+*Please note that a pull request involving a feature that has not been reviewed and approved by the project maintainers may be rejected.*
+
+If you would like to discuss the changes you wish to make, join our [Discord community](https://discord.gg/NGaa9RPCft).
 
 ## Our Standards
 
+Please read our [Coding Standards and Conventions](/coding_conventions.md) before beginning on a contribution.
+
 Examples of behavior that contributes to creating a positive environment
 include: