Dwinzo-Beta/Dwinzo_dev
4
0
Fork 3
Code Issues Pull Requests Packages Projects Releases Wiki Activity

upstream pull + signIn/Up

Browse Source
This commit is contained in:
Jerald_Golden
2025-03-25 17:34:20 +05:30
parent 1259b5fcc8 8456a1e935
commit b44aeb986f
199 changed files with 40127 additions and 40128 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
app/docs/documents/docsifyGuide.md
View File

@@ -1,35 +1,35 @@
# Quick start
It is recommended to install `docsify-cli` globally, which helps initializing and previewing the website locally.
```bash
npm i docsify-cli -g
```
### Initialize
If you want to write the documentation in the `./docs` subdirectory, you can use the `init` command.
```bash
docsify init ./docs
```
### Writing content
After the `init` is complete, you can see the file list in the `./docs` subdirectory.
- `index.html` as the entry file
- `README.md` as the home page
- `.nojekyll` prevents GitHub Pages from ignoring files that begin with an underscore
You can easily update the documentation in `./docs/README.md`, of course you can add more pages.
### Preview your site
Run the local server with `docsify serve`. You can preview your site in your browser on `http://localhost:3000`.
```bash
docsify serve docs
```
# Quick start
It is recommended to install `docsify-cli` globally, which helps initializing and previewing the website locally.
```bash
npm i docsify-cli -g
```
### Initialize
If you want to write the documentation in the `./docs` subdirectory, you can use the `init` command.
```bash
docsify init ./docs
```
### Writing content
After the `init` is complete, you can see the file list in the `./docs` subdirectory.
- `index.html` as the entry file
- `README.md` as the home page
- `.nojekyll` prevents GitHub Pages from ignoring files that begin with an underscore
You can easily update the documentation in `./docs/README.md`, of course you can add more pages.
### Preview your site
Run the local server with `docsify serve`. You can preview your site in your browser on `http://localhost:3000`.
```bash
docsify serve docs
```
?> For more use cases of `docsify-cli`, head over to the [docsify-cli documentation](https://github.com/docsifyjs/docsify-cli).

760
app/docs/documents/documentationGuide.md
View File

@@ -1,380 +1,380 @@
# Why Documentation is Important for Developers
Documentation helps developers work efficiently and ensures projects run smoothly. Here’s why it’s crucial:
1. **Knowledge Sharing**: It helps team members understand the system and communicate effectively, especially when new people join the project.
2. **Code Maintenance**: Good documentation makes it easier to fix bugs, make updates, and keep the code consistent.
3. **Project Longevity**: It ensures that project knowledge is preserved, so future developers can maintain or improve the code without confusion.
4. **Troubleshooting**: Developers can quickly find solutions to problems or understand past decisions, saving time and reducing errors.
5. **Testing and Quality**: Documentation helps ensure the right testing processes are followed, leading to better-quality code.
6. **Efficiency**: It saves time by reducing the need to explain things repeatedly or search for answers.
In short, internal documentation keeps projects organized, helps teams collaborate, and ensures the software can be maintained and improved over time.
---
## Guide to Writing Modular Documentation for React Projects
Modular documentation refers to organizing your documentation into independent, reusable sections or modules. Each module typically covers a specific part of your project, making it easier to update and navigate.
In the context of React, modular documentation should cover both React components and the overall architecture of the app.
### Split Documentation into Smaller Sections
When documenting, break down each part of your codebase into its smallest logical unit:
1. **Functions**: Explain its purpose, inputs (arguments), and outputs (returns).
2. **Components**: Detail props, their types, default values, and the UI they render.
3. **Utilities/Helpers**: Document what a utility does, its inputs, and outputs.
4. **APIs**: Cover the endpoint, request format, and expected response.
Each section should have a consistent structure for easy understanding and reference.
## Documenting Functions
#### Structure for Documenting Functions
1. **Function Name**: A short and descriptive name.
2. **Purpose**: Briefly explain what the function does.
3. **Inputs**:
- List each parameter.
- Include types and default values if applicable.
4. **Output**: Describe the return value and its type.
5. **Code Examples**: Provide a usage example.
#### Example: Utility Function Documentation
````markdown
## `formatDate`
### Purpose
The `formatDate` function converts a `Date` object into a human-readable string format.
### Inputs
| Parameter | Type | Default Value | Description |
| --------- | -------- | ------------- | -------------------------- |
| `date` | `Date` | - | The date object to format. |
| `locale` | `string` | `"en-US"` | The locale for formatting. |
### Output
Returns a `string` representing the formatted date.
### Example
```javascript
import { formatDate } from "./utils";
const date = new Date("2024-11-21");
console.log(formatDate(date)); // Output: "November 21, 2024"
```
````
## Documenting Components
#### Structure for Documenting Components
1. **Component Name**: Name of the React component.
2. **Purpose**: Explain what the component is for and its use case.
3. **Props**:
- List each prop.
- Include type, whether it’s required, and default value.
4. **Behavior**: Describe what the component does and any side effects.
5. **Output**: Explain what the component renders or returns.
6. **Code Examples**: Show how to use the component.
#### Example: Component Documentation
`````markdown
## `Button`
### Purpose
The `Button` component renders a clickable button with customizable styles and behavior.
### Props
| Prop Name | Type | Required | Default Value | Description |
| ---------- | ---------- | -------- | ------------- | ---------------------------------- |
| `label` | `string` | Yes | - | The text displayed on the button. |
| `onClick` | `function` | No | `() => {}` | The function to call when clicked. |
| `disabled` | `boolean` | No | `false` | Disables the button if true. |
| `style` | `object` | No | `{}` | Inline styles for the button. |
### Behavior
- If `disabled` is true, the button cannot be clicked.
- The `onClick` function will only be called when the button is enabled.
### Output
Renders a `<button>` element styled based on the passed props.
### Example
```jsx
import Button from "./components/Button";
<Button
label="Submit"
onClick={() => console.log("Clicked")}
disabled={false}
style={{ color: "white", backgroundColor: "blue" }}
/>;
```
## Documenting Advanced Components
For components with complex functionality (e.g., controlled components, form components, or components interacting with APIs), follow these additional guidelines:
1. **State Management**: Document the state it manages and how to interact with it.
2. **Lifecycle**: If it uses React lifecycle methods or hooks, explain their purpose.
3. **Events**: Document events (e.g., `onChange`, `onBlur`) and their payloads.
#### Example: Complex Component Documentation
````markdown
## `SearchBar`
### Purpose
The `SearchBar` component provides a text input for users to search and emits search queries through the `onSearch` event.
### Props
| Prop Name | Type | Required | Default Value | Description |
| ------------- | ---------- | -------- | ------------- | -------------------------------------------- |
| `placeholder` | `string` | No | `"Search..."` | The placeholder text for the input. |
| `onSearch` | `function` | Yes | - | Callback fired when the search is submitted. |
| `debounce` | `number` | No | `300` | Time in milliseconds to debounce user input. |
### Behavior
1. The component manages the `inputValue` state.
2. After the user stops typing for the `debounce` duration, it triggers the `onSearch` callback with the input value.
### Output
Renders:
- A `<div>` wrapper.
- An `<input>` field styled with default or custom styles.
### Example
```jsx
import SearchBar from "./components/SearchBar";
<SearchBar
placeholder="Search items..."
onSearch={(query) => console.log(query)}
debounce={500}
/>;
```
````
`````
## Documenting Custom Hooks
#### Structure for Documenting Hooks
1. **Hook Name**: Name of the hook.
2. **Purpose**: Why it’s used and what it does.
3. **Inputs**: Parameters passed to the hook.
4. **State/Outputs**: State or values returned by the hook.
5. **Usage**: Show an example.
#### Example: Hook Documentation
````markdown
## `useFetch`
### Purpose
The `useFetch` hook manages data fetching and provides loading, error, and response states.
### Inputs
| Parameter | Type | Required | Default Value | Description |
| --------- | -------- | -------- | ------------- | ------------------------------------- |
| `url` | `string` | Yes | - | The endpoint to fetch data from. |
| `options` | `object` | No | `{}` | Fetch options like headers or method. |
### State/Outputs
| State Name | Type | Description |
| ---------- | --------- | ---------------------------------------- |
| `data` | `any` | The response data from the API. |
| `loading` | `boolean` | Indicates if the request is in progress. |
| `error` | `object` | The error object if the request fails. |
### Example
```javascript
import { useFetch } from "./hooks/useFetch";
const MyComponent = () => {
const { data, loading, error } = useFetch("/api/data");
if (loading) return <p>Loading...</p>;
if (error) return <p>Error: {error.message}</p>;
return <div>{JSON.stringify(data)}</div>;
};
```
````
#### General Best Practices for Modular Documentation
1. **Be Consistent**: Use the same format for all functions, components, and hooks.
2. **Focus on Inputs and Outputs**: Developers care about what they give and what they get.
3. **Use Examples**: Code examples make documentation actionable.
4. **Avoid Overloading**: Document each function/component in its own file if it’s complex.
5. **Explain Behavior**: Describe any side effects, state changes, or interactions.
---
## Guide to Managing Files and Folders for Documentation in Docsify
Docsify is a flexible tool for generating documentation from markdown files. To keep your Docsify-based project well-organized, here’s a guide on how to manage files and folders effectively.
#### 1. Project Structure Overview
A clean folder structure is crucial for scalability, readability, and ease of maintenance. Below is a suggested structure:
```
/docs # Root folder for your Docsify project
│
├── /assets/ # Static resources (images, videos, files, etc.)
│ └── /images/ # Folder for images used in your docs
│ └── gitWorkFlow.svg # Example image used in documentation
│ └── /videos/ # Folder for tutorial videos or related media
│ └── walkthrough.mp4 # old walkthrough presentation
│
├── /documents/ # Folder for the main documentation content
│ └── docsifyGuide.md # Documentation for setting up and using Docsify
│ └── projectStructure.md # Explanation of the project structure and organization
│ └── /components/ # Folder for documentation on different components
│ └── input.md # Input component documentation
│ └── others.md # Other components documentation
│ └── etc.md # Any additional miscellaneous documentation
│
├── /style/ # Folder for custom styles
│ └── style.css # Custom CSS file for styling the documentation
│
└── index.html # Main entry point for Docsify (loads the documentation)
```
---
#### 2. Folder Breakdown
- **/docs**: This is the core folder that contains all of your Markdown (`.md`) files. You can organize these files by sections or topics such as guides, API references, and tutorials. Subfolders like `/guide`, `/reference`, or `/tutorials` help keep related files together.
- **/assets**: This folder is for any images, diagrams, videos, or other static files referenced in your documentation. It's best to organize your media into subfolders based on the section they belong to.
Example:
```
/assets
├── /images/
│ ├── diagram1.png
│ └── screenshot.png
└── /videos/
└── tutorial.mp4
```
- **/lib**: If you want to add custom JavaScript or other scripts to enhance Docsify’s functionality, place them in the `/lib` folder. This can include themes, custom navigation, or interactive features.
---
#### 3. Naming Conventions
Use simple, descriptive names for your files and folders. Avoid spaces in filenames—use hyphens (`-`) instead. For example:
- **Correct**: `installation-guide.md`, `api-reference.md`
- **Incorrect**: `installation guide.md`, `api reference.md`
This keeps URLs and links consistent and easier to handle.
---
#### 4. Organizing Documentation Files
1. **Homepage (index.md)**:
The `index.md` file serves as the homepage for your documentation. It should provide an introduction to the project and link to other sections of your documentation.
2. **Guide Section**:
Place introductory content, installation instructions, and tutorials in the `/guide` folder. Each file should be named based on its content (e.g., `installation.md`, `getting-started.md`).
3. **Reference Section**:
For API documentation or technical references, create a `/reference` folder. You might have files like `api-reference.md`, `config.md`, or `troubleshooting.md`.
4. **Assets**:
Organize images, videos, or diagrams in the `/assets` folder. Keep this structure consistent across sections (e.g., `/assets/images/`, `/assets/videos/`).
---
#### 5. Writing the \_sidebar.md File
The `_sidebar.md` file controls the sidebar navigation in Docsify. It defines the links that appear on the sidebar, which can point to sections of the documentation or external URLs.
Here’s how to structure the `_sidebar.md` file:
- **Basic Structure**:
You can list the sections of your documentation as clickable links. Use Markdown syntax to link to the different `.md` files within your `/docs` folder.
Example:
```markdown
- [Home](/) # Link to the homepage
- [Getting Started](/guide/intro.md) # Link to the "Getting Started" guide
- [API Reference](/reference/api.md) # Link to the API documentation
- [Installation](/guide/installation.md) # Link to the installation guide
```
- **Nested Links**:
To organize sections into subcategories, you can nest links under headings. This helps create a hierarchical structure in the sidebar.
Example:
```markdown
- [Home](/)
- [Guide](/guide/intro.md)
- [Introduction](/guide/intro.md)
- [Usage](/guide/usage.md)
- [API Reference](/reference/api.md)
- [Authentication](/reference/authentication.md)
- [Endpoints](/reference/endpoints.md)
```
- **External Links**:
You can also add external links to resources outside of your Docsify project.
Example:
```markdown
- [External Resource](https://example.com)
```
---
#### 6. Managing Large Projects
For large documentation projects, it’s best to break content into smaller, manageable sections. This will help keep the documentation organized and make it easier for team members to collaborate.
- **Modular Sections**:
Use subfolders like `/getting-started/`, `/setup/`, and `/troubleshooting/` to logically divide your content. Each section should have its own introduction, details, and examples.
- **Indexing**:
Consider creating an `index.md` in each major folder (e.g., `/guide/index.md`, `/reference/index.md`) for clarity and easy navigation.
---
# Why Documentation is Important for Developers
Documentation helps developers work efficiently and ensures projects run smoothly. Here’s why it’s crucial:
1. **Knowledge Sharing**: It helps team members understand the system and communicate effectively, especially when new people join the project.
2. **Code Maintenance**: Good documentation makes it easier to fix bugs, make updates, and keep the code consistent.
3. **Project Longevity**: It ensures that project knowledge is preserved, so future developers can maintain or improve the code without confusion.
4. **Troubleshooting**: Developers can quickly find solutions to problems or understand past decisions, saving time and reducing errors.
5. **Testing and Quality**: Documentation helps ensure the right testing processes are followed, leading to better-quality code.
6. **Efficiency**: It saves time by reducing the need to explain things repeatedly or search for answers.
In short, internal documentation keeps projects organized, helps teams collaborate, and ensures the software can be maintained and improved over time.
---
## Guide to Writing Modular Documentation for React Projects
Modular documentation refers to organizing your documentation into independent, reusable sections or modules. Each module typically covers a specific part of your project, making it easier to update and navigate.
In the context of React, modular documentation should cover both React components and the overall architecture of the app.
### Split Documentation into Smaller Sections
When documenting, break down each part of your codebase into its smallest logical unit:
1. **Functions**: Explain its purpose, inputs (arguments), and outputs (returns).
2. **Components**: Detail props, their types, default values, and the UI they render.
3. **Utilities/Helpers**: Document what a utility does, its inputs, and outputs.
4. **APIs**: Cover the endpoint, request format, and expected response.
Each section should have a consistent structure for easy understanding and reference.
## Documenting Functions
#### Structure for Documenting Functions
1. **Function Name**: A short and descriptive name.
2. **Purpose**: Briefly explain what the function does.
3. **Inputs**:
- List each parameter.
- Include types and default values if applicable.
4. **Output**: Describe the return value and its type.
5. **Code Examples**: Provide a usage example.
#### Example: Utility Function Documentation
````markdown
## `formatDate`
### Purpose
The `formatDate` function converts a `Date` object into a human-readable string format.
### Inputs
| Parameter | Type | Default Value | Description |
| --------- | -------- | ------------- | -------------------------- |
| `date` | `Date` | - | The date object to format. |
| `locale` | `string` | `"en-US"` | The locale for formatting. |
### Output
Returns a `string` representing the formatted date.
### Example
```javascript
import { formatDate } from "./utils";
const date = new Date("2024-11-21");
console.log(formatDate(date)); // Output: "November 21, 2024"
```
````
## Documenting Components
#### Structure for Documenting Components
1. **Component Name**: Name of the React component.
2. **Purpose**: Explain what the component is for and its use case.
3. **Props**:
- List each prop.
- Include type, whether it’s required, and default value.
4. **Behavior**: Describe what the component does and any side effects.
5. **Output**: Explain what the component renders or returns.
6. **Code Examples**: Show how to use the component.
#### Example: Component Documentation
`````markdown
## `Button`
### Purpose
The `Button` component renders a clickable button with customizable styles and behavior.
### Props
| Prop Name | Type | Required | Default Value | Description |
| ---------- | ---------- | -------- | ------------- | ---------------------------------- |
| `label` | `string` | Yes | - | The text displayed on the button. |
| `onClick` | `function` | No | `() => {}` | The function to call when clicked. |
| `disabled` | `boolean` | No | `false` | Disables the button if true. |
| `style` | `object` | No | `{}` | Inline styles for the button. |
### Behavior
- If `disabled` is true, the button cannot be clicked.
- The `onClick` function will only be called when the button is enabled.
### Output
Renders a `<button>` element styled based on the passed props.
### Example
```jsx
import Button from "./components/Button";
<Button
label="Submit"
onClick={() => console.log("Clicked")}
disabled={false}
style={{ color: "white", backgroundColor: "blue" }}
/>;
```
## Documenting Advanced Components
For components with complex functionality (e.g., controlled components, form components, or components interacting with APIs), follow these additional guidelines:
1. **State Management**: Document the state it manages and how to interact with it.
2. **Lifecycle**: If it uses React lifecycle methods or hooks, explain their purpose.
3. **Events**: Document events (e.g., `onChange`, `onBlur`) and their payloads.
#### Example: Complex Component Documentation
````markdown
## `SearchBar`
### Purpose
The `SearchBar` component provides a text input for users to search and emits search queries through the `onSearch` event.
### Props
| Prop Name | Type | Required | Default Value | Description |
| ------------- | ---------- | -------- | ------------- | -------------------------------------------- |
| `placeholder` | `string` | No | `"Search..."` | The placeholder text for the input. |
| `onSearch` | `function` | Yes | - | Callback fired when the search is submitted. |
| `debounce` | `number` | No | `300` | Time in milliseconds to debounce user input. |
### Behavior
1. The component manages the `inputValue` state.
2. After the user stops typing for the `debounce` duration, it triggers the `onSearch` callback with the input value.
### Output
Renders:
- A `<div>` wrapper.
- An `<input>` field styled with default or custom styles.
### Example
```jsx
import SearchBar from "./components/SearchBar";
<SearchBar
placeholder="Search items..."
onSearch={(query) => console.log(query)}
debounce={500}
/>;
```
````
`````
## Documenting Custom Hooks
#### Structure for Documenting Hooks
1. **Hook Name**: Name of the hook.
2. **Purpose**: Why it’s used and what it does.
3. **Inputs**: Parameters passed to the hook.
4. **State/Outputs**: State or values returned by the hook.
5. **Usage**: Show an example.
#### Example: Hook Documentation
````markdown
## `useFetch`
### Purpose
The `useFetch` hook manages data fetching and provides loading, error, and response states.
### Inputs
| Parameter | Type | Required | Default Value | Description |
| --------- | -------- | -------- | ------------- | ------------------------------------- |
| `url` | `string` | Yes | - | The endpoint to fetch data from. |
| `options` | `object` | No | `{}` | Fetch options like headers or method. |
### State/Outputs
| State Name | Type | Description |
| ---------- | --------- | ---------------------------------------- |
| `data` | `any` | The response data from the API. |
| `loading` | `boolean` | Indicates if the request is in progress. |
| `error` | `object` | The error object if the request fails. |
### Example
```javascript
import { useFetch } from "./hooks/useFetch";
const MyComponent = () => {
const { data, loading, error } = useFetch("/api/data");
if (loading) return <p>Loading...</p>;
if (error) return <p>Error: {error.message}</p>;
return <div>{JSON.stringify(data)}</div>;
};
```
````
#### General Best Practices for Modular Documentation
1. **Be Consistent**: Use the same format for all functions, components, and hooks.
2. **Focus on Inputs and Outputs**: Developers care about what they give and what they get.
3. **Use Examples**: Code examples make documentation actionable.
4. **Avoid Overloading**: Document each function/component in its own file if it’s complex.
5. **Explain Behavior**: Describe any side effects, state changes, or interactions.
---
## Guide to Managing Files and Folders for Documentation in Docsify
Docsify is a flexible tool for generating documentation from markdown files. To keep your Docsify-based project well-organized, here’s a guide on how to manage files and folders effectively.
#### 1. Project Structure Overview
A clean folder structure is crucial for scalability, readability, and ease of maintenance. Below is a suggested structure:
```
/docs # Root folder for your Docsify project
│
├── /assets/ # Static resources (images, videos, files, etc.)
│ └── /images/ # Folder for images used in your docs
│ └── gitWorkFlow.svg # Example image used in documentation
│ └── /videos/ # Folder for tutorial videos or related media
│ └── walkthrough.mp4 # old walkthrough presentation
│
├── /documents/ # Folder for the main documentation content
│ └── docsifyGuide.md # Documentation for setting up and using Docsify
│ └── projectStructure.md # Explanation of the project structure and organization
│ └── /components/ # Folder for documentation on different components
│ └── input.md # Input component documentation
│ └── others.md # Other components documentation
│ └── etc.md # Any additional miscellaneous documentation
│
├── /style/ # Folder for custom styles
│ └── style.css # Custom CSS file for styling the documentation
│
└── index.html # Main entry point for Docsify (loads the documentation)
```
---
#### 2. Folder Breakdown
- **/docs**: This is the core folder that contains all of your Markdown (`.md`) files. You can organize these files by sections or topics such as guides, API references, and tutorials. Subfolders like `/guide`, `/reference`, or `/tutorials` help keep related files together.
- **/assets**: This folder is for any images, diagrams, videos, or other static files referenced in your documentation. It's best to organize your media into subfolders based on the section they belong to.
Example:
```
/assets
├── /images/
│ ├── diagram1.png
│ └── screenshot.png
└── /videos/
└── tutorial.mp4
```
- **/lib**: If you want to add custom JavaScript or other scripts to enhance Docsify’s functionality, place them in the `/lib` folder. This can include themes, custom navigation, or interactive features.
---
#### 3. Naming Conventions
Use simple, descriptive names for your files and folders. Avoid spaces in filenames—use hyphens (`-`) instead. For example:
- **Correct**: `installation-guide.md`, `api-reference.md`
- **Incorrect**: `installation guide.md`, `api reference.md`
This keeps URLs and links consistent and easier to handle.
---
#### 4. Organizing Documentation Files
1. **Homepage (index.md)**:
The `index.md` file serves as the homepage for your documentation. It should provide an introduction to the project and link to other sections of your documentation.
2. **Guide Section**:
Place introductory content, installation instructions, and tutorials in the `/guide` folder. Each file should be named based on its content (e.g., `installation.md`, `getting-started.md`).
3. **Reference Section**:
For API documentation or technical references, create a `/reference` folder. You might have files like `api-reference.md`, `config.md`, or `troubleshooting.md`.
4. **Assets**:
Organize images, videos, or diagrams in the `/assets` folder. Keep this structure consistent across sections (e.g., `/assets/images/`, `/assets/videos/`).
---
#### 5. Writing the \_sidebar.md File
The `_sidebar.md` file controls the sidebar navigation in Docsify. It defines the links that appear on the sidebar, which can point to sections of the documentation or external URLs.
Here’s how to structure the `_sidebar.md` file:
- **Basic Structure**:
You can list the sections of your documentation as clickable links. Use Markdown syntax to link to the different `.md` files within your `/docs` folder.
Example:
```markdown
- [Home](/) # Link to the homepage
- [Getting Started](/guide/intro.md) # Link to the "Getting Started" guide
- [API Reference](/reference/api.md) # Link to the API documentation
- [Installation](/guide/installation.md) # Link to the installation guide
```
- **Nested Links**:
To organize sections into subcategories, you can nest links under headings. This helps create a hierarchical structure in the sidebar.
Example:
```markdown
- [Home](/)
- [Guide](/guide/intro.md)
- [Introduction](/guide/intro.md)
- [Usage](/guide/usage.md)
- [API Reference](/reference/api.md)
- [Authentication](/reference/authentication.md)
- [Endpoints](/reference/endpoints.md)
```
- **External Links**:
You can also add external links to resources outside of your Docsify project.
Example:
```markdown
- [External Resource](https://example.com)
```
---
#### 6. Managing Large Projects
For large documentation projects, it’s best to break content into smaller, manageable sections. This will help keep the documentation organized and make it easier for team members to collaborate.
- **Modular Sections**:
Use subfolders like `/getting-started/`, `/setup/`, and `/troubleshooting/` to logically divide your content. Each section should have its own introduction, details, and examples.
- **Indexing**:
Consider creating an `index.md` in each major folder (e.g., `/guide/index.md`, `/reference/index.md`) for clarity and easy navigation.
---

676
app/docs/documents/gitNotes.md
View File

@@ -1,338 +1,338 @@
## Git basic Workflow
<p align="center">
<img src="../assets/images/gitWorkFlow.svg" alt="Git basic Workflow">
<p align="center">Fig.1 - Git basic Workflow</p>
</p>
---
## Git Commands
1. Initialize git:
```bash
git init
```
2. Check remote repository:
```bash
git remote
git remote -v
```
3. Connect to remote repository (optional):
If remote repository is not connected use,
```bash
git remote add origin http://185.100.212.76:7776/Vishnu/modeling_app.git
```
To change url use,
```bash
git remote set-url origin http://185.100.212.76:7776/Vishnu/modeling_app.git
```
4. Fetch from origin:
On fetch mention --all to pull all branches or mention remote_name and branch_name to fetch a particular branch.
Use --force to perform force Pull.
```bash
git fetch
git pull
```
5. Staging and Commit changes:
- "." indicated all changed files will be staged.
- For, specific file replace "." with the path to the specific file or directory(folder).
- "commit message" - replace text in this phrase to your commit discription.
**Staging**
```bash
git add .
git add path/to/directory_or_file
```
To Unstage all files that were added to the staging area but does not affect the working directory:
```bash
git reset
```
**Commit**
```bash
git commit -m "commit message"
```
Creates a new commit that undoes the changes introduced by the specified commit, use --hard for discarding all changes since that commit (Warning: This command can permanently delete data.):
```bash
git revert commit_hash
```
6. Inspecting Commits:
- View the commit history:
```bash
git log
```
- View a graph of commits:
```bash
git log --graph --oneline --all
```
7. Push to remote repository:
- If the branch is creted for the first time and dose not located in the remote repsitory. Use,
```bash
git push --set-upstream origin new_branch_name
```
- Normal push
```bash
git push origin new_branch_name
```
- Force push and Safer force push
```bash
git push --force
git push --force-with-lease
```
- Delete branch in remote repository
```bash
git push origin --delete branch_name
```
8. Creating and Switching Branches:
- To check current branch name. Use,
```bash
git remote
```
- To checkout from current branch and move to another branch. Use,
```bash
git checkout branch_name
```
- To checkout from current branch and create new branch. Use,
```bash
git checkout -b new_branch_name
```
9. Merging branches:
- Merges the specified branch to the current active branch:
```bash
git merge branch_name
```
- This will only perform the merge if it can be fast-forwarded. If a fast-forward isn't possible, Git will abort the merge:
```bash
git merge --ff-only branch_name
```
- Provide a custom merge commit message:
```bash
git merge -m "Custom merge message" branch_name
```
- Merge without committing automatically:
```bash
git merge --no-commit branch_name
```
- Continue the merge after resolving conflicts:
```bash
git merge --continue
```
- Abort a merge in progress:
```bash
git merge --abort
```
10. Stash changes:
- Stashes changes made in current branch:
```bash
git stash
```
- Stashes changes made in current branch with message:
```bash
git stash save "message"
```
- Apply Latest stash and apply and remove form stash list:
```bash
git stash apply
git stash pop
```
- View Stash:
```bash
git stash list
```
- Clear all stashes:
```bash
git stash clear
```
- Remove the latest stash:
```bash
git stash drop
```
11. Branch commands:
- To View all local and remote branches
```bash
git branch
git branch -a
```
- To Create branch
```bash
git branch branch_name
```
- To switch between branch
```bash
git checkout branch_name
```
Alternatively if you want to bring the changes to the new branch,
```bash
git switch branch_name
```
- To switch between branch
```bash
git checkout -b branch_name
```
Alternatively,
```bash
git switch -c branch_name
```
- To rename branch
```bash
git branch -m old_branch_name new_branch_name
```
- To Delete branch (use -D to force delete)
```bash
git branch -d branch_name
```
12. Other git comments consiered usefull in previous encounters:
- press q to exit git response
- Prevent git from creating **zoneIdentifier** files
```bash
git config core.protectNTFS false
```
---
## Git Branching
<p align="center">
<img src="../assets/images/gitBranching.svg" alt="Git Branching">
<p align="center">Fig.2 - Git Branching</p>
</p>
This diagram represents a branching model for managing the development of a software project. It uses different branches to organize and control how code changes are developed, tested, and released. Here’s a breakdown of the key concepts, simplified for someone new:
### **Main Components**
1. **Main Branch** (blue line):
- This branch represents the "production" or "live" version of the project.
- Only stable and tested versions of the code are added here.
- Releases like `v0.1`, `v0.2`, and `v1.0` are tagged here.
2. **Develop Branch** (purple line):
- This is where active development happens.
- Features or fixes are integrated here before they are prepared for a release.
- It acts as a staging area for new work to ensure it’s functional and complete.
3. **Feature Branches** (green lines):
- These branches are used to develop specific features or tasks.
- Developers create a new branch for each feature and work on it independently.
- Once complete, they are merged into the **Develop Branch**.
4. **Release Branch** (teal line):
- Before a release is finalized, a release branch is created.
- Final fixes and testing are done here to ensure stability.
- Once complete, it is merged into both **Main** and **Develop** branches to mark the release.
5. **Hotfix Branch** (red line):
- This branch is for urgent fixes to the live code.
- If an issue is found in the **Main Branch** (e.g., a bug in `v0.1`), a **Hotfix Branch** is created.
- After fixing, it is merged into both **Main** and **Develop** to ensure the fix is applied everywhere.
### **Workflow Summary**
1. **Start a Feature:**
- Create a feature branch from the **Develop Branch**.
- Work on your task and complete it.
2. **Integrate Your Work:**
- When your feature is ready, merge it back into the **Develop Branch**.
3. **Prepare a Release:**
- When the team decides to release a version, a **Release Branch** is created from **Develop**.
- Final adjustments are made before merging it into **Main**.
4. **Fix Urgent Problems:**
- If a critical issue is found in production, create a **Hotfix Branch** from **Main**, fix it, and merge it into both **Main** and **Develop**.
This system helps keep work organized, ensures stability for the live version, and allows teams to work on different features or fixes simultaneously. It’s designed to make collaboration and code integration smoother.
---
## Aditional notes
**On start the app asks wheather to pull from git or not.**
- If you are connected to the remote repository, type "y" or "yes" to perform the pull action. The app will automatically abort the start process if the pull operation encounters any issues to prevent abnormalities.
- If you are not connected to the remote repository, type "n" or "no" to skip the pull action and proceed with starting the app.
## Git basic Workflow
<p align="center">
<img src="../assets/images/gitWorkFlow.svg" alt="Git basic Workflow">
<p align="center">Fig.1 - Git basic Workflow</p>
</p>
---
## Git Commands
1. Initialize git:
```bash
git init
```
2. Check remote repository:
```bash
git remote
git remote -v
```
3. Connect to remote repository (optional):
If remote repository is not connected use,
```bash
git remote add origin http://185.100.212.76:7776/Vishnu/modeling_app.git
```
To change url use,
```bash
git remote set-url origin http://185.100.212.76:7776/Vishnu/modeling_app.git
```
4. Fetch from origin:
On fetch mention --all to pull all branches or mention remote_name and branch_name to fetch a particular branch.
Use --force to perform force Pull.
```bash
git fetch
git pull
```
5. Staging and Commit changes:
- "." indicated all changed files will be staged.
- For, specific file replace "." with the path to the specific file or directory(folder).
- "commit message" - replace text in this phrase to your commit discription.
**Staging**
```bash
git add .
git add path/to/directory_or_file
```
To Unstage all files that were added to the staging area but does not affect the working directory:
```bash
git reset
```
**Commit**
```bash
git commit -m "commit message"
```
Creates a new commit that undoes the changes introduced by the specified commit, use --hard for discarding all changes since that commit (Warning: This command can permanently delete data.):
```bash
git revert commit_hash
```
6. Inspecting Commits:
- View the commit history:
```bash
git log
```
- View a graph of commits:
```bash
git log --graph --oneline --all
```
7. Push to remote repository:
- If the branch is creted for the first time and dose not located in the remote repsitory. Use,
```bash
git push --set-upstream origin new_branch_name
```
- Normal push
```bash
git push origin new_branch_name
```
- Force push and Safer force push
```bash
git push --force
git push --force-with-lease
```
- Delete branch in remote repository
```bash
git push origin --delete branch_name
```
8. Creating and Switching Branches:
- To check current branch name. Use,
```bash
git remote
```
- To checkout from current branch and move to another branch. Use,
```bash
git checkout branch_name
```
- To checkout from current branch and create new branch. Use,
```bash
git checkout -b new_branch_name
```
9. Merging branches:
- Merges the specified branch to the current active branch:
```bash
git merge branch_name
```
- This will only perform the merge if it can be fast-forwarded. If a fast-forward isn't possible, Git will abort the merge:
```bash
git merge --ff-only branch_name
```
- Provide a custom merge commit message:
```bash
git merge -m "Custom merge message" branch_name
```
- Merge without committing automatically:
```bash
git merge --no-commit branch_name
```
- Continue the merge after resolving conflicts:
```bash
git merge --continue
```
- Abort a merge in progress:
```bash
git merge --abort
```
10. Stash changes:
- Stashes changes made in current branch:
```bash
git stash
```
- Stashes changes made in current branch with message:
```bash
git stash save "message"
```
- Apply Latest stash and apply and remove form stash list:
```bash
git stash apply
git stash pop
```
- View Stash:
```bash
git stash list
```
- Clear all stashes:
```bash
git stash clear
```
- Remove the latest stash:
```bash
git stash drop
```
11. Branch commands:
- To View all local and remote branches
```bash
git branch
git branch -a
```
- To Create branch
```bash
git branch branch_name
```
- To switch between branch
```bash
git checkout branch_name
```
Alternatively if you want to bring the changes to the new branch,
```bash
git switch branch_name
```
- To switch between branch
```bash
git checkout -b branch_name
```
Alternatively,
```bash
git switch -c branch_name
```
- To rename branch
```bash
git branch -m old_branch_name new_branch_name
```
- To Delete branch (use -D to force delete)
```bash
git branch -d branch_name
```
12. Other git comments consiered usefull in previous encounters:
- press q to exit git response
- Prevent git from creating **zoneIdentifier** files
```bash
git config core.protectNTFS false
```
---
## Git Branching
<p align="center">
<img src="../assets/images/gitBranching.svg" alt="Git Branching">
<p align="center">Fig.2 - Git Branching</p>
</p>
This diagram represents a branching model for managing the development of a software project. It uses different branches to organize and control how code changes are developed, tested, and released. Here’s a breakdown of the key concepts, simplified for someone new:
### **Main Components**
1. **Main Branch** (blue line):
- This branch represents the "production" or "live" version of the project.
- Only stable and tested versions of the code are added here.
- Releases like `v0.1`, `v0.2`, and `v1.0` are tagged here.
2. **Develop Branch** (purple line):
- This is where active development happens.
- Features or fixes are integrated here before they are prepared for a release.
- It acts as a staging area for new work to ensure it’s functional and complete.
3. **Feature Branches** (green lines):
- These branches are used to develop specific features or tasks.
- Developers create a new branch for each feature and work on it independently.
- Once complete, they are merged into the **Develop Branch**.
4. **Release Branch** (teal line):
- Before a release is finalized, a release branch is created.
- Final fixes and testing are done here to ensure stability.
- Once complete, it is merged into both **Main** and **Develop** branches to mark the release.
5. **Hotfix Branch** (red line):
- This branch is for urgent fixes to the live code.
- If an issue is found in the **Main Branch** (e.g., a bug in `v0.1`), a **Hotfix Branch** is created.
- After fixing, it is merged into both **Main** and **Develop** to ensure the fix is applied everywhere.
### **Workflow Summary**
1. **Start a Feature:**
- Create a feature branch from the **Develop Branch**.
- Work on your task and complete it.
2. **Integrate Your Work:**
- When your feature is ready, merge it back into the **Develop Branch**.
3. **Prepare a Release:**
- When the team decides to release a version, a **Release Branch** is created from **Develop**.
- Final adjustments are made before merging it into **Main**.
4. **Fix Urgent Problems:**
- If a critical issue is found in production, create a **Hotfix Branch** from **Main**, fix it, and merge it into both **Main** and **Develop**.
This system helps keep work organized, ensures stability for the live version, and allows teams to work on different features or fixes simultaneously. It’s designed to make collaboration and code integration smoother.
---
## Aditional notes
**On start the app asks wheather to pull from git or not.**
- If you are connected to the remote repository, type "y" or "yes" to perform the pull action. The app will automatically abort the start process if the pull operation encounters any issues to prevent abnormalities.
- If you are not connected to the remote repository, type "n" or "no" to skip the pull action and proceed with starting the app.

394
app/docs/documents/markdownGuide.md
View File

@@ -1,197 +1,197 @@
# How to Write a Markdown (.md) File for Large-Scale Projects
## Introduction
Markdown (MD) is a lightweight markup language widely used in software development for documentation purposes. It is simple, easy to read, and can be converted to HTML, making it ideal for collaborative and large-scale projects. This guide will help you create well-structured, clear, and professional Markdown files tailored for use in large-scale projects.
---
## Obsidian
#### What is Obsidian
Obsidian is a powerful, feature-rich note-taking and knowledge management application designed for individuals and teams. It is highly customizable and based on plain text Markdown files, making it a versatile tool for creating, organizing, and connecting ideas. It’s particularly popular among professionals, students, and researchers who use it for personal knowledge management (PKM), journaling, writing, and task management.
All notes in Obsidian are plain text Markdown files stored locally on your computer. This ensures that your notes are portable, future-proof, and easy to access outside the application.
#### How to Get Started
1. Download and Install:
- [Obsidian’s website](https://obsidian.md/) provides downloads for all major platforms.
2. Create a Vault:
- A "vault" is a folder where all your Markdown notes are stored. You can have multiple vaults for different purposes.
3. Start Taking Notes:
- Create new notes using Markdown syntax and link them using Note Name.
4. For more:
- [Read official Obsidian documentation](https://help.obsidian.md/Home)
---
## Understanding Markdown Syntax
Markdown provides a straightforward syntax for formatting text. Below are the essential elements you'll need to master:
#### **1. Headers**
Headers define the structure of your document. Use `#` to denote headings, with more `#` symbols indicating smaller headings.
- Example:
```markdown
# Main Header
## Subheader
### Sub-Subheader
```
#### **2. Lists**
Markdown supports ordered and unordered lists for organizing information.
- Unordered list:
```markdown
- Item 1
- Item 2
```
- Ordered list:
```markdown
1. Step 1
2. Step 2
```
#### **3. Text Formatting**
- Bold: `**bold text**`
- Italic: `*italic text*`
- Inline Code: `` `inline code` ``
- Strikethrough: `~~strikethrough~~`
#### **4. Links and Images**
- Link: `[Link Text](URL)`
- Image: `![Alt Text](Image URL)`
#### **5. Tables**
Tables are useful for presenting structured data.
- Example:
```markdown
| Header 1 | Header 2 |
| -------- | -------- |
| Row 1 | Data |
| Row 2 | Data |
```
#### **6. Code Blocks**
Use triple backticks to include code blocks. Specify the programming language for syntax highlighting.
- Example:
````markdown
```jsx
console.log("Hello world");
```
````
---
## Key Guidelines for Large-Scale Projects
#### **1. Understand the Project Structure**
Before you start writing, familiarize yourself with the project's directory and the purpose of the documentation. In large projects, MD files often serve specific roles, such as:
- **README.md**: A high-level overview of the project.
- **CONTRIBUTING.md**: Guidelines for contributing to the project.
- **CHANGELOG.md**: Records of changes made over time.
- **API.md**: Detailed documentation of APIs.
#### **2. Write for Your Audience**
- Identify the primary readers of the document (e.g., developers, testers, stakeholders).
- Use technical terms appropriately and explain jargon when necessary.
#### **3. Maintain Consistency**
- Follow a consistent style, tone, and structure across all Markdown files.
- Adhere to any project-specific conventions or style guides.
#### **4. Use Comments Wisely**
Markdown does not support native comments, but you can use HTML-style comments for notes that should not appear in the rendered file.
- Example:
```markdown
<!-- This is a comment -->
```
---
## Checklist for Writing a Quality Markdown File
1. **Start with a Purpose**
Begin your document with a clear purpose or summary of what it covers.
2. **Follow a Logical Flow**
Organize information hierarchically using headings and subheadings.
3. **Be Concise and Clear**
Avoid redundant information. Use simple language where possible.
4. **Incorporate Visual Aids**
Use tables, images, or diagrams to explain complex topics.
5. **Test and Validate**
- Render your Markdown file locally or in the project’s preferred Markdown viewer to ensure formatting works as expected.
- Use tools like **MarkdownLint** to check for common syntax errors.
6. **Link to Other Resources**
Provide hyperlinks to related MD files or external resources.
7. **Version Control**
Use version control (e.g., Git) to track changes and maintain a clear history of updates.
---
## Example: Simple README.md Template
````markdown
# Project Title
## Description
Provide a brief overview of the project, its purpose, and key features.
## Installation
Explain how to set up the project.
```bash
# Example installation command
pip install project-name
```
````
## Usage
Provide examples of how to use the project.
```python
# Example usage
from project import feature
feature.run()
```
---
## External Resources
1. ▶️ [The Only Markdown Crash Course You Will Ever Need](https://www.youtube.com/watch?v=_PPWWRV6gbA&ab_channel=WebDevSimplified)
2. 📄 [Basic writing and formatting syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
---
# How to Write a Markdown (.md) File for Large-Scale Projects
## Introduction
Markdown (MD) is a lightweight markup language widely used in software development for documentation purposes. It is simple, easy to read, and can be converted to HTML, making it ideal for collaborative and large-scale projects. This guide will help you create well-structured, clear, and professional Markdown files tailored for use in large-scale projects.
---
## Obsidian
#### What is Obsidian
Obsidian is a powerful, feature-rich note-taking and knowledge management application designed for individuals and teams. It is highly customizable and based on plain text Markdown files, making it a versatile tool for creating, organizing, and connecting ideas. It’s particularly popular among professionals, students, and researchers who use it for personal knowledge management (PKM), journaling, writing, and task management.
All notes in Obsidian are plain text Markdown files stored locally on your computer. This ensures that your notes are portable, future-proof, and easy to access outside the application.
#### How to Get Started
1. Download and Install:
- [Obsidian’s website](https://obsidian.md/) provides downloads for all major platforms.
2. Create a Vault:
- A "vault" is a folder where all your Markdown notes are stored. You can have multiple vaults for different purposes.
3. Start Taking Notes:
- Create new notes using Markdown syntax and link them using Note Name.
4. For more:
- [Read official Obsidian documentation](https://help.obsidian.md/Home)
---
## Understanding Markdown Syntax
Markdown provides a straightforward syntax for formatting text. Below are the essential elements you'll need to master:
#### **1. Headers**
Headers define the structure of your document. Use `#` to denote headings, with more `#` symbols indicating smaller headings.
- Example:
```markdown
# Main Header
## Subheader
### Sub-Subheader
```
#### **2. Lists**
Markdown supports ordered and unordered lists for organizing information.
- Unordered list:
```markdown
- Item 1
- Item 2
```
- Ordered list:
```markdown
1. Step 1
2. Step 2
```
#### **3. Text Formatting**
- Bold: `**bold text**`
- Italic: `*italic text*`
- Inline Code: `` `inline code` ``
- Strikethrough: `~~strikethrough~~`
#### **4. Links and Images**
- Link: `[Link Text](URL)`
- Image: `![Alt Text](Image URL)`
#### **5. Tables**
Tables are useful for presenting structured data.
- Example:
```markdown
| Header 1 | Header 2 |
| -------- | -------- |
| Row 1 | Data |
| Row 2 | Data |
```
#### **6. Code Blocks**
Use triple backticks to include code blocks. Specify the programming language for syntax highlighting.
- Example:
````markdown
```jsx
console.log("Hello world");
```
````
---
## Key Guidelines for Large-Scale Projects
#### **1. Understand the Project Structure**
Before you start writing, familiarize yourself with the project's directory and the purpose of the documentation. In large projects, MD files often serve specific roles, such as:
- **README.md**: A high-level overview of the project.
- **CONTRIBUTING.md**: Guidelines for contributing to the project.
- **CHANGELOG.md**: Records of changes made over time.
- **API.md**: Detailed documentation of APIs.
#### **2. Write for Your Audience**
- Identify the primary readers of the document (e.g., developers, testers, stakeholders).
- Use technical terms appropriately and explain jargon when necessary.
#### **3. Maintain Consistency**
- Follow a consistent style, tone, and structure across all Markdown files.
- Adhere to any project-specific conventions or style guides.
#### **4. Use Comments Wisely**
Markdown does not support native comments, but you can use HTML-style comments for notes that should not appear in the rendered file.
- Example:
```markdown
<!-- This is a comment -->
```
---
## Checklist for Writing a Quality Markdown File
1. **Start with a Purpose**
Begin your document with a clear purpose or summary of what it covers.
2. **Follow a Logical Flow**
Organize information hierarchically using headings and subheadings.
3. **Be Concise and Clear**
Avoid redundant information. Use simple language where possible.
4. **Incorporate Visual Aids**
Use tables, images, or diagrams to explain complex topics.
5. **Test and Validate**
- Render your Markdown file locally or in the project’s preferred Markdown viewer to ensure formatting works as expected.
- Use tools like **MarkdownLint** to check for common syntax errors.
6. **Link to Other Resources**
Provide hyperlinks to related MD files or external resources.
7. **Version Control**
Use version control (e.g., Git) to track changes and maintain a clear history of updates.
---
## Example: Simple README.md Template
````markdown
# Project Title
## Description
Provide a brief overview of the project, its purpose, and key features.
## Installation
Explain how to set up the project.
```bash
# Example installation command
pip install project-name
```
````
## Usage
Provide examples of how to use the project.
```python
# Example usage
from project import feature
feature.run()
```
---
## External Resources
1. ▶️ [The Only Markdown Crash Course You Will Ever Need](https://www.youtube.com/watch?v=_PPWWRV6gbA&ab_channel=WebDevSimplified)
2. 📄 [Basic writing and formatting syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
---

352
app/docs/documents/notes.md
View File

@@ -1,176 +1,176 @@
## /temp/ files
I’ve set up the repository to ignore all folders named `temp`. This is a space you can use for temporary or experimental files without worrying about affecting the application or pushing these files to Gitea.
- **Purpose**: Use the `temp` folder to store temporary files, logs, or scripts for testing purposes.
- **Ignored by Git**: All `temp` folders are excluded from version control using the `.gitignore` rule `**/temp/`. These files will not be committed or pushed to the repository.
- **Best Practices**: Please avoid storing critical or shared files here. Use it for temporary work only, and clean up files when no longer needed.
This should help us maintain a clean repository while giving everyone the freedom to experiment.
---
## Standardized File Structure and Coding Guidelines
To improve our codebase's readability, maintainability, and scalability, we’re adopting a standardized file structure and coding practices. Here’s a summary:
1. **File Structure**:
- **Components (`.tsx`)**: All files that return HTML/JSX will be React components with a `.tsx` extension. They should focus on UI logic and presentation.
- **Purpose**: Files with the `.tsx` extension are reserved for React components that return JSX/HTML.
- **Location**: Components should be organized based on their purpose or scope within the application. Example:
```
src/
components/
Header.tsx
Footer.tsx
pages/
Home.tsx
About.tsx
```
- **Naming Convention**: Component filenames should use PascalCase, matching the component name (e.g., `Header.tsx` for a `Header` component).
- **Example**:
```tsx
/**
* Header component that displays the application's navigation bar.
*
* @returns {JSX.Element} A navigation bar with links.
*/
const Header: React.FC = () => {
return (
<header>
<nav>
<a href="/">Home</a>
<a href="/about">About</a>
</nav>
</header>
);
};
export default Header;
```
- **Functions (`.ts`)**: All helper functions or business logic will go into `.ts` files, separate from the components.
- **Purpose**: Files with the `.ts` extension are for helper functions, utility logic, or other non-React code that does not return JSX/HTML.
- **Location**: Place utility files in a `utils` directory or within a directory relevant to their context. Example:
```
src/
utils/
calculateTotal.ts
formatDate.ts
hooks/
useFetch.ts
```
- **Naming Convention**: Use camelCase for filenames that describe the primary function (e.g., `calculateTotal.ts` for a `calculateTotal` function).
- **Example**:
```ts
/**
* Calculates the total price based on items and tax rate.
*
* @param {number[]} prices - Array of item prices.
* @param {number} taxRate - Tax rate as a decimal.
* @returns {number} Total price including tax.
*/
export const calculateTotal = (
prices: number[],
taxRate: number
): number => {
const subtotal = prices.reduce((sum, price) => sum + price, 0);
return subtotal + subtotal * taxRate;
};
```
---
## Commenting Standards
To improve code readability and understanding, every function and component should include comments explaining its purpose, inputs, and outputs. Here’s how we’ll approach this:
1. **React Components**:
- Include a **high-level description** of what the component does.
- Specify the **props** it accepts, along with their types.
- Specify the **return type** (`JSX.Element` for React components).
**Example**:
```tsx
/**
* Button component that triggers an action when clicked.
*
* @param {object} props - The props object.
* @param {string} props.label - The text to display on the button.
* @param {() => void} props.onClick - The callback function triggered when the button is clicked.
* @returns {JSX.Element} A styled button element.
*/
const Button: React.FC<{ label: string; onClick: () => void }> = ({
label,
onClick,
}) => {
return <button onClick={onClick}>{label}</button>;
};
export default Button;
```
2. **Functions**:
- Include a **detailed description** of what the function does.
- Specify the **parameters**, their types, and what they represent.
- Specify the **return type** and what it represents.
**Example**:
```ts
/**
* Converts a date string to a readable format.
*
* @param {string} date - A date string in ISO format (e.g., "2024-11-21").
* @returns {string} The formatted date (e.g., "November 21, 2024").
*/
export const formatDate = (date: string): string => {
const options: Intl.DateTimeFormatOptions = {
year: "numeric",
month: "long",
day: "numeric",
};
return new Date(date).toLocaleDateString(undefined, options);
};
```
3. **Commenting Standards**:
- Each function and component should have a comment explaining:
- What it does.
- The props or parameters it accepts (including types).
- What it returns and why.
4. **Why This Matters**:
- This structure helps us maintain a clean, modular codebase. It also makes the project easier to navigate for new and existing team members.
---
## File Naming Guidelines
To maintain consistency and professionalism in our codebase, we are standardizing the way we name files. This is crucial for readability, collaboration, and avoiding potential issues across different operating systems.
We are introducing a standardized **file naming convention** to maintain consistency across the codebase. Here are the key points:
1. **File Naming**:
- All file names must follow the **camelCase** convention (e.g., `headerComponent.tsx`, `calculateTotal.ts`).
- This ensures uniformity and avoids case sensitivity issues.
2. **Pre-Commit Hook**:
- A pre-commit hook will automatically rename files to camelCase if they don’t comply.
- Please double-check that your imports match the updated file names to avoid runtime errors.
3. **What You Need to Do**:
- Name files correctly in camelCase from the start.
- If a file is renamed during a commit, ensure all imports are updated to reflect the new name.
4. **Why This Matters**:
- Consistent file naming improves readability and reduces issues when working in teams or across different operating systems.
## /temp/ files
I’ve set up the repository to ignore all folders named `temp`. This is a space you can use for temporary or experimental files without worrying about affecting the application or pushing these files to Gitea.
- **Purpose**: Use the `temp` folder to store temporary files, logs, or scripts for testing purposes.
- **Ignored by Git**: All `temp` folders are excluded from version control using the `.gitignore` rule `**/temp/`. These files will not be committed or pushed to the repository.
- **Best Practices**: Please avoid storing critical or shared files here. Use it for temporary work only, and clean up files when no longer needed.
This should help us maintain a clean repository while giving everyone the freedom to experiment.
---
## Standardized File Structure and Coding Guidelines
To improve our codebase's readability, maintainability, and scalability, we’re adopting a standardized file structure and coding practices. Here’s a summary:
1. **File Structure**:
- **Components (`.tsx`)**: All files that return HTML/JSX will be React components with a `.tsx` extension. They should focus on UI logic and presentation.
- **Purpose**: Files with the `.tsx` extension are reserved for React components that return JSX/HTML.
- **Location**: Components should be organized based on their purpose or scope within the application. Example:
```
src/
components/
Header.tsx
Footer.tsx
pages/
Home.tsx
About.tsx
```
- **Naming Convention**: Component filenames should use PascalCase, matching the component name (e.g., `Header.tsx` for a `Header` component).
- **Example**:
```tsx
/**
* Header component that displays the application's navigation bar.
*
* @returns {JSX.Element} A navigation bar with links.
*/
const Header: React.FC = () => {
return (
<header>
<nav>
<a href="/">Home</a>
<a href="/about">About</a>
</nav>
</header>
);
};
export default Header;
```
- **Functions (`.ts`)**: All helper functions or business logic will go into `.ts` files, separate from the components.
- **Purpose**: Files with the `.ts` extension are for helper functions, utility logic, or other non-React code that does not return JSX/HTML.
- **Location**: Place utility files in a `utils` directory or within a directory relevant to their context. Example:
```
src/
utils/
calculateTotal.ts
formatDate.ts
hooks/
useFetch.ts
```
- **Naming Convention**: Use camelCase for filenames that describe the primary function (e.g., `calculateTotal.ts` for a `calculateTotal` function).
- **Example**:
```ts
/**
* Calculates the total price based on items and tax rate.
*
* @param {number[]} prices - Array of item prices.
* @param {number} taxRate - Tax rate as a decimal.
* @returns {number} Total price including tax.
*/
export const calculateTotal = (
prices: number[],
taxRate: number
): number => {
const subtotal = prices.reduce((sum, price) => sum + price, 0);
return subtotal + subtotal * taxRate;
};
```
---
## Commenting Standards
To improve code readability and understanding, every function and component should include comments explaining its purpose, inputs, and outputs. Here’s how we’ll approach this:
1. **React Components**:
- Include a **high-level description** of what the component does.
- Specify the **props** it accepts, along with their types.
- Specify the **return type** (`JSX.Element` for React components).
**Example**:
```tsx
/**
* Button component that triggers an action when clicked.
*
* @param {object} props - The props object.
* @param {string} props.label - The text to display on the button.
* @param {() => void} props.onClick - The callback function triggered when the button is clicked.
* @returns {JSX.Element} A styled button element.
*/
const Button: React.FC<{ label: string; onClick: () => void }> = ({
label,
onClick,
}) => {
return <button onClick={onClick}>{label}</button>;
};
export default Button;
```
2. **Functions**:
- Include a **detailed description** of what the function does.
- Specify the **parameters**, their types, and what they represent.
- Specify the **return type** and what it represents.
**Example**:
```ts
/**
* Converts a date string to a readable format.
*
* @param {string} date - A date string in ISO format (e.g., "2024-11-21").
* @returns {string} The formatted date (e.g., "November 21, 2024").
*/
export const formatDate = (date: string): string => {
const options: Intl.DateTimeFormatOptions = {
year: "numeric",
month: "long",
day: "numeric",
};
return new Date(date).toLocaleDateString(undefined, options);
};
```
3. **Commenting Standards**:
- Each function and component should have a comment explaining:
- What it does.
- The props or parameters it accepts (including types).
- What it returns and why.
4. **Why This Matters**:
- This structure helps us maintain a clean, modular codebase. It also makes the project easier to navigate for new and existing team members.
---
## File Naming Guidelines
To maintain consistency and professionalism in our codebase, we are standardizing the way we name files. This is crucial for readability, collaboration, and avoiding potential issues across different operating systems.
We are introducing a standardized **file naming convention** to maintain consistency across the codebase. Here are the key points:
1. **File Naming**:
- All file names must follow the **camelCase** convention (e.g., `headerComponent.tsx`, `calculateTotal.ts`).
- This ensures uniformity and avoids case sensitivity issues.
2. **Pre-Commit Hook**:
- A pre-commit hook will automatically rename files to camelCase if they don’t comply.
- Please double-check that your imports match the updated file names to avoid runtime errors.
3. **What You Need to Do**:
- Name files correctly in camelCase from the start.
- If a file is renamed during a commit, ensure all imports are updated to reflect the new name.
4. **Why This Matters**:
- Consistent file naming improves readability and reduces issues when working in teams or across different operating systems.

214
app/docs/documents/projectStructure.md
View File

@@ -1,107 +1,107 @@
# Project Folder Structure
This document provides a detailed description of the purpose of each folder in the project by root level, along with the folder hierarchy.
## Folder Hierarchy
```
📁 src
├── 📁 assets
├── 📁 components
├── 📁 functions
├── 📁 hooks
├── 📁 modules
│ ├── 📁 builder
│ ├── 📁 simulation
│ └── 📁 visualization
├── 📁 services
├── 📁 store
├── 📁 styles
├── 📁 tests
├── 📁 types
├── 📁 utils
├── App.css
├── App.tsx
├── index.css
├── main.tsx
└── vite-env.d.ts
```
---
## Description of Each Folder
### 📁 `src`
The root directory for all source code related to the application.
#### 📁 `assets`
- **Purpose:** Contains static assets such as images, icons, fonts, or other resources.
- **Example:**
- `react.svg`: A static SVG file used in the project.
#### 📁 `components`
- **Purpose:** Contains reusable React components, serving as building blocks for the user interface.
- **Example:**
- Buttons, modals, headers, and forms.
#### 📁 `functions`
- **Purpose:** Stores pure functions or logic that can be reused across the application.
- **Example:**
- Utility functions for data transformation or computation.
#### 📁 `hooks`
- **Purpose:** Holds custom React hooks for managing specific logic or behaviors.
- **Example:**
- Hooks for state management, API calls, or reusable effects.
#### 📁 `modules`
- **Purpose:** Organizes high-level, feature-specific code into subdirectories.
- **📁 builder:** Manages functionalities and components related to building or configuring features.
- **📁 simulation:** Handles processes or logic related to simulations or dynamic scenarios.
- **📁 visualization:** Focuses on displaying data visually, such as charts, graphs, or interactive UI elements.
#### 📁 `services`
- **Purpose:** Encapsulates external service interactions, such as API calls or library integrations.
- **Example:**
- REST API clients or authentication handlers.
#### 📁 `store`
- **Purpose:** Contains state management logic and configurations for tools like Redux or Zustand.
- **Example:**
- Redux slices, context providers, or global state stores.
#### 📁 `styles`
- **Purpose:** Includes global CSS, SCSS, or theming resources.
- **Example:**
- Global styles, theme variables, or resets.
#### 📁 `tests`
- **Purpose:** Stores test files for unit testing, integration testing, and mock data.
- **Example:**
- Test files (`*.test.tsx`, `*.spec.ts`) or mock utilities.
#### 📁 `types`
- **Purpose:** Contains shared TypeScript type definitions and interfaces.
- **Example:**
- Type declarations for props, data models, or API responses.
#### 📁 `utils`
- **Purpose:** Includes general-purpose utility files that don’t fit into other specific folders.
- **Example:**
- Helper functions like debouncers or date formatters.
---
## Root-Level Files
### `App.tsx`
- **Purpose:** The root React component, initializing the main application layout and logic.
### `index.css`
- **Purpose:** Contains global styles applied throughout the application.
### `main.tsx`
- **Purpose:** The entry point of the app, rendering the React application and setting up the React DOM.
### `vite-env.d.ts`
- **Purpose:** TypeScript environment configuration file for Vite.
# Project Folder Structure
This document provides a detailed description of the purpose of each folder in the project by root level, along with the folder hierarchy.
## Folder Hierarchy
```
📁 src
├── 📁 assets
├── 📁 components
├── 📁 functions
├── 📁 hooks
├── 📁 modules
│ ├── 📁 builder
│ ├── 📁 simulation
│ └── 📁 visualization
├── 📁 services
├── 📁 store
├── 📁 styles
├── 📁 tests
├── 📁 types
├── 📁 utils
├── App.css
├── App.tsx
├── index.css
├── main.tsx
└── vite-env.d.ts
```
---
## Description of Each Folder
### 📁 `src`
The root directory for all source code related to the application.
#### 📁 `assets`
- **Purpose:** Contains static assets such as images, icons, fonts, or other resources.
- **Example:**
- `react.svg`: A static SVG file used in the project.
#### 📁 `components`
- **Purpose:** Contains reusable React components, serving as building blocks for the user interface.
- **Example:**
- Buttons, modals, headers, and forms.
#### 📁 `functions`
- **Purpose:** Stores pure functions or logic that can be reused across the application.
- **Example:**
- Utility functions for data transformation or computation.
#### 📁 `hooks`
- **Purpose:** Holds custom React hooks for managing specific logic or behaviors.
- **Example:**
- Hooks for state management, API calls, or reusable effects.
#### 📁 `modules`
- **Purpose:** Organizes high-level, feature-specific code into subdirectories.
- **📁 builder:** Manages functionalities and components related to building or configuring features.
- **📁 simulation:** Handles processes or logic related to simulations or dynamic scenarios.
- **📁 visualization:** Focuses on displaying data visually, such as charts, graphs, or interactive UI elements.
#### 📁 `services`
- **Purpose:** Encapsulates external service interactions, such as API calls or library integrations.
- **Example:**
- REST API clients or authentication handlers.
#### 📁 `store`
- **Purpose:** Contains state management logic and configurations for tools like Redux or Zustand.
- **Example:**
- Redux slices, context providers, or global state stores.
#### 📁 `styles`
- **Purpose:** Includes global CSS, SCSS, or theming resources.
- **Example:**
- Global styles, theme variables, or resets.
#### 📁 `tests`
- **Purpose:** Stores test files for unit testing, integration testing, and mock data.
- **Example:**
- Test files (`*.test.tsx`, `*.spec.ts`) or mock utilities.
#### 📁 `types`
- **Purpose:** Contains shared TypeScript type definitions and interfaces.
- **Example:**
- Type declarations for props, data models, or API responses.
#### 📁 `utils`
- **Purpose:** Includes general-purpose utility files that don’t fit into other specific folders.
- **Example:**
- Helper functions like debouncers or date formatters.
---
## Root-Level Files
### `App.tsx`
- **Purpose:** The root React component, initializing the main application layout and logic.
### `index.css`
- **Purpose:** Contains global styles applied throughout the application.
### `main.tsx`
- **Purpose:** The entry point of the app, rendering the React application and setting up the React DOM.
### `vite-env.d.ts`
- **Purpose:** TypeScript environment configuration file for Vite.