Updated the /docs directory

.markdownlint.json

@@ -1,4 +1,5 @@
 {
+	"MD007": false,
 	"MD010": false,
 	"MD013": false
 }

README.md

@@ -9,47 +9,49 @@ My portfolio website to showcase (and brag) about my all my projects!
 
 ## Getting Started
 
-Go to <https://alexjsully.me> to see this portfolio!
+Visit <https://alexjsully.me> to view the live portfolio.
 
-## Browser Compatibilities
+To run locally:
 
-| Chrome | Firefox | Edge | Safari | Opera | Tor | Mobile |
-| ------ | ------- | ---- | ------ | ----- | --- | ------ |
-| ✔     | ✔      | ✔   | ✔     | ✔    | ✔  | ✔     |
-
-## Installation/Open
+```bash
+git clone https://github.com/AlexJSully/alexjsully-portfolio.git
 
-You can open a live version of my portfolio website at <https://alexjsully.me>
+cd alexjsully-portfolio
 
-If you would like to run or modify my portfolio locally, clone the repository with git by running the following command:
+npm ci
 
-```git
-git clone https://github.com/AlexJSully/alexjsully-portfolio.git
+npm run dev
 ```
 
-Then run `npm ci`, change to the appropriate directory and then `npm dev`. My portfolio will run at <http://localhost:3000/>.
+The app will be available at <http://localhost:3000/>.
 
-## Known issues
+## Browser Compatibility
 
-I aim to make my portfolio as perfect as possible but unfortunately, there may be some unforeseen bugs. If you manage to find one that is not here, feel free to create a [bug report](https://github.com/AlexJSully/alexjsully-portfolio/issues/new/choose) so we can fix it.
+| Chrome | Firefox | Edge | Safari | Opera | Tor | Mobile |
+| ------ | ------- | ---- | ------ | ----- | --- | ------ |
+| ✔     | ✔      | ✔   | ✔     | ✔    | ✔  | ✔     |
+
+## Known Issues
+
+If you find a bug, please create a [bug report](https://github.com/AlexJSully/alexjsully-portfolio/issues/new/choose).
 
 - None at the moment
 
-## Sponsorship
+## Contributing
 
-If you want to support my work, you can through the following methods:
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. All contributions are welcome!
 
-- [BTC](3Lp4pwF5nXqwFA62BYx4DSvDswyYpskBog) - 3Lp4pwF5nXqwFA62BYx4DSvDswyYpskBog
-- [ETH](0xc6EB17BD7cbe5976Bfc4f845669cD66Ff340a1A2) - 0xc6EB17BD7cbe5976Bfc4f845669cD66Ff340a1A2
+## Sponsorship
 
-## Contributing
+If you want to support my work:
 
-Please read [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
+- [BTC](3Lp4pwF5nXqwFA62BYx4DSvDswyYpskBog)
+- [ETH](0xc6EB17BD7cbe5976Bfc4f845669cD66Ff340a1A2)
 
 ## License
 
 [GPL-3.0](LICENSE)
 
 ## Authors
 
-- Alexander Sullivan - [GitHub](https://github.com/AlexJSully), [Twitter](https://twitter.com/alexjsully), [LinkedIn](https://www.linkedin.com/in/alexanderjsullivan/), [Website](https://alexjsully.me/)
+- Alexander Joo-Hyun Sullivan - [GitHub](https://github.com/AlexJSully), [Twitter](https://twitter.com/alexjsully), [LinkedIn](https://www.linkedin.com/in/alexanderjsullivan/), [Website](https://alexjsully.me/)

docs/architecture/components/index.md

@@ -0,0 +1,55 @@
+# Components Documentation
+
+This document describes the internal architecture, relationships, and usage of major UI components in the AlexJSully Portfolio project. Components are modular, reusable, and styled with Material-UI and Emotion.
+
+## 📦 Component List & Hierarchy
+
+- [ProjectsGrid](./projects.md): Displays a grid of projects.
+- [Publications](./publications.md): Lists publications.
+- [Footer](./socials.md): Shows social media links.
+- [Navbar](../architecture/index.md): Navigation bar (see architecture for layout details).
+- [Banner, CookieSnackbar, StarsBackground]: Utility and visual components.
+
+### Component Hierarchy
+
+```mermaid
+flowchart TD
+    App --> Navbar
+    App --> Banner
+    App --> ProjectsGrid
+    App --> Publications
+    App --> Footer
+    App --> CookieSnackbar
+    App --> StarsBackground
+```
+
+## 🔍 Component Details
+
+- **Navbar:** Top navigation bar, links to sections. Handles navigation, accessibility, and analytics logging.
+- **Banner:** Header section, may include avatar and intro. Displays profile and branding.
+- **ProjectsGrid:** Displays project cards in a grid. Handles filtering, analytics, and responsive layout.
+- **Publications:** Lists publications with metadata. Supports links to external resources.
+- **Footer:** Social media links and copyright. Includes contact and resume links.
+- **CookieSnackbar:** Shows cookie consent. Manages cookie state and user interaction.
+- **StarsBackground:** Visual background effect. Renders animated stars for visual appeal.
+
+## 🏗️ Relationships & Composition
+
+- Components are composed in page layouts (see `GeneralLayout.tsx`).
+- Data is passed via props or imported from `src/data/`.
+- Styling is handled via MUI and Emotion.
+- Utility components (Banner, CookieSnackbar, StarsBackground) are used for branding and user experience.
+
+## 🧩 How Components Work
+
+Components are located in `src/components/` and are imported using TypeScript path aliases (see `tsconfig.json`).
+Each component is tested with Jest and/or Cypress for reliability.
+
+## 🔗 Related Docs
+
+- [Architecture Overview](../architecture/index.md)
+- [Usage Guides](../usage/index.md)
+
+---
+
+💡 **Tip:** See each component's documentation for usage examples, diagrams, and integration details.

docs/architecture/components/projects.md

@@ -0,0 +1,99 @@
+# Projects Documentation
+
+## Overview
+
+This document explains how the projects grid is displayed and how to add new projects to the codebase.
+
+## Projects Grid Display
+
+The projects grid is displayed using the `ProjectsGrid` component located in [ProjectsGrid.tsx](../../src/components/projects/ProjectsGrid.tsx). This component creates a grid layout to showcase the projects.
+
+### Key Elements
+
+- **State Management:** Uses React `useState` to toggle featured/all projects.
+- **Grid Layout:** Responsive grid via MUI Grid/Stack.
+- **Project Cards:** Thumbnail, name, title, employer, resource links.
+
+### Flowchart
+
+```mermaid
+flowchart LR
+    A[ProjectsGrid Component] -->|Fetches| B[Projects Data]
+    B --> C[Maps Projects to Grid Items]
+    C --> D[Displays Project Cards]
+    D --> E[Project Thumbnail]
+    D --> F[Project Name]
+    D --> G[Project Title - Employer]
+    D --> I[Links]
+    E --> J[Thumbnail Image]
+    I --> K[Link Buttons]
+    D --> L[YouTube Video]
+```
+
+```ts
+{
+  name: 'Project Name',
+  title: 'Project Title',
+  employer: 'Employer',
+  thumbnail: 'image/path',
+  links: [{ type: 'github', url: '...' }],
+  // ...other fields
+}
+```
+
+```ts
+{
+  name: 'Project Name',
+  title: 'Project Title',
+  employer: 'Employer',
+  thumbnail: 'image/path',
+  links: [{ type: 'github', url: '...' }],
+  // ...other fields
+}
+```
+
+## 🔗 Related Docs
+
+- [Component Overview](./index.md)
+- [System Architecture](../architecture/index.md)
+
+```json
+{
+	"name": "Project Name",
+	"id": "project-id", // unique identifier for the project (associated with the image file name or publication)
+	"description": "Project description", // optional
+	"employer": "Employer Name", // optional
+	"employerURL": "https://employer-website.com", // required if employer is provided
+	"title": "Job Title",
+	"publication": "https://publication-url.com", // optional
+	"type": "Employment", // or 'Personal Project', 'School (MSc)', etc.
+	"url": "https://project-url.com", // optional
+	"urls": [
+		// this is used to create a series of buttons with links
+		{
+			"text": "Link Text",
+			"tooltip": "Tooltip description",
+			"icon": "IconComponent", // this is a JSX component
+			"url": "https://link-url.com"
+		}
+	],
+	"color": "#colorCode",
+	"dates": {
+		"startDate": "YYYY-MM",
+		"endDate": "YYYY-MM" // or current if ongoing
+	},
+	"showcase": true, // or false
+	"objectFit": "contain", // optional, cover is used if nothing is provided
+	"youtubeURL": "https://www.youtube.com/embed/{videoID}?autoplay=1&mute=1&cc_load_policy=1&controls=1" // optional: displays a YouTube video to play in the card if mouse hovered over
+}
+```
+
+### Adding Thumbnail Images
+
+To add a thumbnail image for the new project, place the image in the appropriate directory:
+
+1. **Navigate to the images directory**: Go to the [public image projects directory](../../public/images/projects).
+2. **Create a new directory**: Create a new directory with the project ID (e.g., `new-project`).
+3. **Add the thumbnail image**: Place the thumbnail image in the new directory and name it `thumbnail.webp`. Recommended to use `.webp` format for better performance.
+
+By following these steps, you can successfully add new projects to the projects grid.

docs/architecture/configs.md

@@ -0,0 +1,88 @@
+# Configs Module Documentation
+
+This document describes configuration files and environment setup in AlexJSully's Portfolio project, their roles, technical details, and how to update or extend them.
+
+## 📦 Purpose
+
+Configs manage environment variables, service integrations, and global settings for the app. They enable features like Firebase, Sentry error tracking, and custom runtime options.
+
+## 🏗️ Structure
+
+- **Location:** `src/configs/`
+- **Example files:**
+    - `firebase.ts`: Firebase configuration and initialization
+    - `firebase.test.ts`: Test configuration for Firebase
+- **Related config files:**
+    - `.env`: Environment variables (API keys, secrets)
+    - `next.config.js`: Next.js build/runtime config
+    - `sentry.client.config.ts`, `sentry.server.config.ts`, `sentry.edge.config.ts`: Sentry error tracking
+
+## 🔍 Usage Examples
+
+### Importing Firebase Config
+
+```ts
+import firebaseConfig from '@configs/firebase';
+
+// Initialize Firebase app
+```
+
+### Using Environment Variables
+
+```ts
+const apiKey = process.env.NEXT_PUBLIC_API_KEY;
+```
+
+### Sentry Configuration
+
+```ts
+import * as Sentry from '@sentry/nextjs';
+
+Sentry.init({ dsn: process.env.NEXT_PUBLIC_SENTRY_DSN });
+```
+
+### Next.js Config Example
+
+```js
+// next.config.js
+module.exports = {
+	reactStrictMode: true,
+	env: {
+		NEXT_PUBLIC_API_KEY: process.env.NEXT_PUBLIC_API_KEY,
+	},
+};
+```
+
+## 🧩 Integration & Relationships
+
+- Configs are imported by components, helpers, and backend logic for environment-specific behavior.
+- Environment variables are loaded via `.env` and referenced in code using `process.env.*`.
+- Sentry config files enable error tracking for client, server, and edge runtimes.
+
+## 🛠️ Extending Configs
+
+- Add new config files in `src/configs/` for new services.
+- Update `.env` for new environment variables.
+- Document config changes in `README.md` and relevant docs.
+
+## 🔗 Related Docs
+
+- [System Architecture](./index.md)
+
+- [PWA Documentation](./pwa.md)
+
+💡 **Tip:** Keep sensitive keys in `.env` and never commit them to version control. Document all config changes for maintainability.
+
+## 🛠️ Practical Guidance
+
+- Store sensitive keys and secrets in `.env` (never commit to git).
+- Document required environment variables for contributors in README.md or a dedicated section.
+- Update config files when adding new services or changing integrations.
+- Validate config changes with `npm run validate`.
+- For Sentry, update DSN and environment in all sentry config files and test error reporting.
+
+## 🧩 Relationships
+
+- Used by data modules, components, and Next.js for service integration.
+- Sentry configs for error tracking.
+- Firebase config for backend/data features.