Skip to content

Commit ce5d057

Browse files
AlexJSullyCopilot
AlexJSully
and
Copilot
authored
Updated the /docs directory (#537)
Using GitHub Copilot GPT 4.1 Agent, updated the `/docs` directory to make more detailed of what is going on within the codebase. --------- Co-authored-by: Copilot <[email protected]>
1 parent 785f079 commit ce5d057

File tree

23 files changed

+1734
-892
lines changed

23 files changed

+1734
-892
lines changed

‎.markdownlint.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
{
2+
"MD007": false,
23
"MD010": false,
34
"MD013": false
45
}

‎README.md‎

Lines changed: 23 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -9,47 +9,49 @@ My portfolio website to showcase (and brag) about my all my projects!
99

1010
## Getting Started
1111

12-
Go to <https://alexjsully.me> to see this portfolio!
12+
Visit <https://alexjsully.me> to view the live portfolio.
1313

14-
## Browser Compatibilities
14+
To run locally:
1515

16-
| Chrome | Firefox | Edge | Safari | Opera | Tor | Mobile |
17-
| ------ | ------- | ---- | ------ | ----- | --- | ------ |
18-
| ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
19-
20-
## Installation/Open
16+
```bash
17+
git clone https://github.com/AlexJSully/alexjsully-portfolio.git
2118

22-
You can open a live version of my portfolio website at <https://alexjsully.me>
19+
cd alexjsully-portfolio
2320

24-
If you would like to run or modify my portfolio locally, clone the repository with git by running the following command:
21+
npm ci
2522

26-
```git
27-
git clone https://github.com/AlexJSully/alexjsully-portfolio.git
23+
npm run dev
2824
```
2925

30-
Then run `npm ci`, change to the appropriate directory and then `npm dev`. My portfolio will run at <http://localhost:3000/>.
26+
The app will be available at <http://localhost:3000/>.
3127

32-
## Known issues
28+
## Browser Compatibility
3329

34-
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.
30+
| Chrome | Firefox | Edge | Safari | Opera | Tor | Mobile |
31+
| ------ | ------- | ---- | ------ | ----- | --- | ------ |
32+
| ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
33+
34+
## Known Issues
35+
36+
If you find a bug, please create a [bug report](https://github.com/AlexJSully/alexjsully-portfolio/issues/new/choose).
3537

3638
- None at the moment
3739

38-
## Sponsorship
40+
## Contributing
3941

40-
If you want to support my work, you can through the following methods:
42+
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. All contributions are welcome!
4143

42-
- [BTC](3Lp4pwF5nXqwFA62BYx4DSvDswyYpskBog) - 3Lp4pwF5nXqwFA62BYx4DSvDswyYpskBog
43-
- [ETH](0xc6EB17BD7cbe5976Bfc4f845669cD66Ff340a1A2) - 0xc6EB17BD7cbe5976Bfc4f845669cD66Ff340a1A2
44+
## Sponsorship
4445

45-
## Contributing
46+
If you want to support my work:
4647

47-
Please read [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
48+
- [BTC](3Lp4pwF5nXqwFA62BYx4DSvDswyYpskBog)
49+
- [ETH](0xc6EB17BD7cbe5976Bfc4f845669cD66Ff340a1A2)
4850

4951
## License
5052

5153
[GPL-3.0](LICENSE)
5254

5355
## Authors
5456

55-
- Alexander Sullivan - [GitHub](https://github.com/AlexJSully), [Twitter](https://twitter.com/alexjsully), [LinkedIn](https://www.linkedin.com/in/alexanderjsullivan/), [Website](https://alexjsully.me/)
57+
- 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‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Components Documentation
2+
3+
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.
4+
5+
## 📦 Component List & Hierarchy
6+
7+
- [ProjectsGrid](./projects.md): Displays a grid of projects.
8+
- [Publications](./publications.md): Lists publications.
9+
- [Footer](./socials.md): Shows social media links.
10+
- [Navbar](../architecture/index.md): Navigation bar (see architecture for layout details).
11+
- [Banner, CookieSnackbar, StarsBackground]: Utility and visual components.
12+
13+
### Component Hierarchy
14+
15+
```mermaid
16+
flowchart TD
17+
App --> Navbar
18+
App --> Banner
19+
App --> ProjectsGrid
20+
App --> Publications
21+
App --> Footer
22+
App --> CookieSnackbar
23+
App --> StarsBackground
24+
```
25+
26+
## 🔍 Component Details
27+
28+
- **Navbar:** Top navigation bar, links to sections. Handles navigation, accessibility, and analytics logging.
29+
- **Banner:** Header section, may include avatar and intro. Displays profile and branding.
30+
- **ProjectsGrid:** Displays project cards in a grid. Handles filtering, analytics, and responsive layout.
31+
- **Publications:** Lists publications with metadata. Supports links to external resources.
32+
- **Footer:** Social media links and copyright. Includes contact and resume links.
33+
- **CookieSnackbar:** Shows cookie consent. Manages cookie state and user interaction.
34+
- **StarsBackground:** Visual background effect. Renders animated stars for visual appeal.
35+
36+
## 🏗️ Relationships & Composition
37+
38+
- Components are composed in page layouts (see `GeneralLayout.tsx`).
39+
- Data is passed via props or imported from `src/data/`.
40+
- Styling is handled via MUI and Emotion.
41+
- Utility components (Banner, CookieSnackbar, StarsBackground) are used for branding and user experience.
42+
43+
## 🧩 How Components Work
44+
45+
Components are located in `src/components/` and are imported using TypeScript path aliases (see `tsconfig.json`).
46+
Each component is tested with Jest and/or Cypress for reliability.
47+
48+
## 🔗 Related Docs
49+
50+
- [Architecture Overview](../architecture/index.md)
51+
- [Usage Guides](../usage/index.md)
52+
53+
---
54+
55+
💡 **Tip:** See each component's documentation for usage examples, diagrams, and integration details.

‎docs/architecture/components/projects.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Projects Documentation
2+
3+
## Overview
4+
5+
This document explains how the projects grid is displayed and how to add new projects to the codebase.
6+
7+
## Projects Grid Display
8+
9+
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.
10+
11+
### Key Elements
12+
13+
- **State Management:** Uses React `useState` to toggle featured/all projects.
14+
- **Grid Layout:** Responsive grid via MUI Grid/Stack.
15+
- **Project Cards:** Thumbnail, name, title, employer, resource links.
16+
17+
### Flowchart
18+
19+
```mermaid
20+
flowchart LR
21+
A[ProjectsGrid Component] -->|Fetches| B[Projects Data]
22+
B --> C[Maps Projects to Grid Items]
23+
C --> D[Displays Project Cards]
24+
D --> E[Project Thumbnail]
25+
D --> F[Project Name]
26+
D --> G[Project Title - Employer]
27+
D --> I[Links]
28+
E --> J[Thumbnail Image]
29+
I --> K[Link Buttons]
30+
D --> L[YouTube Video]
31+
```
32+
33+
```ts
34+
{
35+
name: 'Project Name',
36+
title: 'Project Title',
37+
employer: 'Employer',
38+
thumbnail: 'image/path',
39+
links: [{ type: 'github', url: '...' }],
40+
// ...other fields
41+
}
42+
```
43+
44+
## 🔗 Related Docs
45+
46+
- [Component Overview](./index.md)
47+
- [System Architecture](../architecture/index.md)
48+
49+
```json
50+
{
51+
"name": "Project Name",
52+
"id": "project-id", // unique identifier for the project (associated with the image file name or publication)
53+
"description": "Project description", // optional
54+
"employer": "Employer Name", // optional
55+
"employerURL": "https://employer-website.com", // required if employer is provided
56+
"title": "Job Title",
57+
"publication": "https://publication-url.com", // optional
58+
"type": "Employment", // or 'Personal Project', 'School (MSc)', etc.
59+
"url": "https://project-url.com", // optional
60+
"urls": [
61+
// this is used to create a series of buttons with links
62+
{
63+
"text": "Link Text",
64+
"tooltip": "Tooltip description",
65+
"icon": "IconComponent", // this is a JSX component
66+
"url": "https://link-url.com"
67+
}
68+
],
69+
"color": "#colorCode",
70+
"dates": {
71+
"startDate": "YYYY-MM",
72+
"endDate": "YYYY-MM" // or current if ongoing
73+
},
74+
"showcase": true, // or false
75+
"objectFit": "contain", // optional, cover is used if nothing is provided
76+
"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
77+
}
78+
```
79+
80+
### Adding Thumbnail Images
81+
82+
To add a thumbnail image for the new project, place the image in the appropriate directory:
83+
84+
1. **Navigate to the images directory**: Go to the [public image projects directory](../../public/images/projects).
85+
2. **Create a new directory**: Create a new directory with the project ID (e.g., `new-project`).
86+
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.
87+
88+
By following these steps, you can successfully add new projects to the projects grid.

docs/components/publications.md renamed to docs/architecture/components/publications.md

File renamed without changes.

docs/components/socials.md renamed to docs/architecture/components/socials.md

File renamed without changes.

‎docs/architecture/configs.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Configs Module Documentation
2+
3+
This document describes configuration files and environment setup in AlexJSully's Portfolio project, their roles, technical details, and how to update or extend them.
4+
5+
## 📦 Purpose
6+
7+
Configs manage environment variables, service integrations, and global settings for the app. They enable features like Firebase, Sentry error tracking, and custom runtime options.
8+
9+
## 🏗️ Structure
10+
11+
- **Location:** `src/configs/`
12+
- **Example files:**
13+
- `firebase.ts`: Firebase configuration and initialization
14+
- `firebase.test.ts`: Test configuration for Firebase
15+
- **Related config files:**
16+
- `.env`: Environment variables (API keys, secrets)
17+
- `next.config.js`: Next.js build/runtime config
18+
- `sentry.client.config.ts`, `sentry.server.config.ts`, `sentry.edge.config.ts`: Sentry error tracking
19+
20+
## 🔍 Usage Examples
21+
22+
### Importing Firebase Config
23+
24+
```ts
25+
import firebaseConfig from '@configs/firebase';
26+
27+
// Initialize Firebase app
28+
```
29+
30+
### Using Environment Variables
31+
32+
```ts
33+
const apiKey = process.env.NEXT_PUBLIC_API_KEY;
34+
```
35+
36+
### Sentry Configuration
37+
38+
```ts
39+
import * as Sentry from '@sentry/nextjs';
40+
41+
Sentry.init({ dsn: process.env.NEXT_PUBLIC_SENTRY_DSN });
42+
```
43+
44+
### Next.js Config Example
45+
46+
```js
47+
// next.config.js
48+
module.exports = {
49+
reactStrictMode: true,
50+
env: {
51+
NEXT_PUBLIC_API_KEY: process.env.NEXT_PUBLIC_API_KEY,
52+
},
53+
};
54+
```
55+
56+
## 🧩 Integration & Relationships
57+
58+
- Configs are imported by components, helpers, and backend logic for environment-specific behavior.
59+
- Environment variables are loaded via `.env` and referenced in code using `process.env.*`.
60+
- Sentry config files enable error tracking for client, server, and edge runtimes.
61+
62+
## 🛠️ Extending Configs
63+
64+
- Add new config files in `src/configs/` for new services.
65+
- Update `.env` for new environment variables.
66+
- Document config changes in `README.md` and relevant docs.
67+
68+
## 🔗 Related Docs
69+
70+
- [System Architecture](./index.md)
71+
72+
- [PWA Documentation](./pwa.md)
73+
74+
💡 **Tip:** Keep sensitive keys in `.env` and never commit them to version control. Document all config changes for maintainability.
75+
76+
## 🛠️ Practical Guidance
77+
78+
- Store sensitive keys and secrets in `.env` (never commit to git).
79+
- Document required environment variables for contributors in README.md or a dedicated section.
80+
- Update config files when adding new services or changing integrations.
81+
- Validate config changes with `npm run validate`.
82+
- For Sentry, update DSN and environment in all sentry config files and test error reporting.
83+
84+
## 🧩 Relationships
85+
86+
- Used by data modules, components, and Next.js for service integration.
87+
- Sentry configs for error tracking.
88+
- Firebase config for backend/data features.

‎docs/architecture/data.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Data Architecture
2+
3+
This document explains how data is structured, managed, and integrated in the AlexJSully Portfolio project, with technical details and TypeScript interfaces.
4+
5+
## 📦 Data Sources
6+
7+
### Static Data
8+
9+
- `src/data/projects.ts`: Project details (array of project objects)
10+
- `src/data/publications.ts`: Publication details (array of publication objects)
11+
- `src/data/socials.ts`: Social media links (array of social link objects)
12+
- `src/data/keywords.ts`: SEO keywords (string array)
13+
14+
### Dynamic Data
15+
16+
- Firebase integration for real-time and remote data (see `src/configs/firebase.ts`)
17+
18+
## Data Flow
19+
20+
```mermaid
21+
sequenceDiagram
22+
participant User
23+
participant Page
24+
participant Layout
25+
participant Component
26+
participant DataFile
27+
User->>Page: Requests page
28+
Page->>Layout: Loads layout
29+
Layout->>Component: Renders components
30+
Component->>DataFile: Imports data
31+
DataFile-->>Component: Returns data
32+
Component-->>Layout: Passes rendered output
33+
Layout-->>Page: Passes rendered output
34+
Page-->>User: Displays page
35+
```
36+
37+
## Data Usage in the Codebase
38+
39+
- Data files in `src/data/` provide static and dynamic content for components and pages.
40+
- Components import data directly using TypeScript path aliases (e.g., `@data/projects`).
41+
- Layouts and pages aggregate data from multiple sources for rendering.
42+
- Dynamic data (e.g., from Firebase) is fetched in helper functions or via API routes, then passed to components as props.
43+
- TypeScript interfaces ensure type safety and validation for all imported data.
44+
- Data is used for:
45+
- Rendering project lists, publication cards, and social links
46+
- SEO metadata and keywords
47+
- Navigation and page structure
48+
- Analytics and user interaction tracking
49+
50+
## 🧩 Data Structures & Interfaces
51+
52+
- Data is exported as arrays/objects and imported into components using TypeScript path aliases.
53+
- TypeScript interfaces define the structure and validation for each data type.
54+
- Example:
55+
56+
```ts
57+
// src/data/projects.ts
58+
export interface Project {
59+
id: string;
60+
title: string;
61+
description: string;
62+
url: string;
63+
tags: string[];
64+
}
65+
export const projects: Project[] = [ ... ];
66+
```
67+
68+
## 🔗 Integration & Usage
69+
70+
- Components import data for rendering lists, cards, and details.
71+
- Layouts use data for navigation and page structure.
72+
- Data is tested and validated using TypeScript and Jest.
73+
74+
## 🛠️ Extending Data
75+
76+
- Add new data files in `src/data/`.
77+
- Define TypeScript interfaces for new data types.
78+
- Update components to consume new data as needed.
79+
80+
## 🔗 Related Docs
81+
82+
- [Component Documentation](../components/index.md)
83+
- [System Architecture](./index.md)
84+
85+
💡 **Tip:** Use TypeScript interfaces for all data structures to ensure type safety and maintainability.

0 commit comments

Comments
 (0)