Skip to content

Commit e0486c7

Browse files
AlexJSullyAlexJSully
authored
Update audit quality prompt (#574)
Update audit quality prompt to make compliance depend on the codebase itself. Also updated docs.
1 parent 92318d9 commit e0486c7

File tree

11 files changed

+578
-1195
lines changed

11 files changed

+578
-1195
lines changed

‎.github/prompts/audit-quality.prompt.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -166,16 +166,22 @@ Act as a **Principal Code Reviewer, Security Auditor, and Refactoring Architect*
166166

167167
**Objective:** Ensure compliance with applicable data protection and privacy regulations.
168168

169+
Not all regulations apply to every codebase. Determine which regulations are in scope based on the system's data subjects, geography, data types, and regulated activities. Only perform compliance checks for regulations that apply, and explicitly state why any listed regulation is out of scope.
170+
169171
Check compliance with:
170172

171173
- **United States:** HIPAA (Health Insurance Portability and Accountability Act)
174+
- Applies when the system handles protected health information (PHI) for a covered entity or business associate.
172175
- **European Union & Ireland:** GDPR (General Data Protection Regulation)
176+
- Applies when the system processes personal data, especially if it profiles users, tracks behavior, or makes decisions that affect individuals.
173177
- **Canada (Federal):** PIPEDA (Personal Information Protection and Electronic Documents Act)
178+
- Applies when the system processes personal information for commercial activities in the private sector.
174179
- **Canada - Ontario (Provincial):** PHIPA (Personal Health Information Protection Act)
180+
- Applies when the system handles personal health information for a health information custodian or their agent.
175181
- **South Korea:** PIPA (Personal Information Protection Act)
176-
- **Vietnam:** PDPL (Personal Data Protection Law)
182+
- Applies when the system processes personal information, including identifiers, contact data, or behavioral data.
177183

178-
Verify:
184+
For each applicable regulation, verify:
179185

180186
- Right to access, rectification, erasure, and data portability
181187
- Breach notification procedures

‎docs/architecture/app-directory.md‎

Lines changed: 46 additions & 265 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,23 @@
11
# App Directory (Next.js)
22

3-
This document explains the Next.js App Router directory structure and implementation in the Alexander Sullivan's Portfolio project.
4-
5-
## Overview
6-
7-
The project uses Next.js 16+ with the App Router architecture located in [`src/app/`](../../src/app/). This modern routing system uses file-system based routing with server and client components.
8-
9-
## Directory Structure
10-
11-
```text
12-
src/app/
13-
├── layout.tsx # Root layout with metadata
14-
├── page.tsx # Home page component
15-
├── manifest.ts # PWA manifest configuration
16-
├── robots.ts # SEO robots.txt generator
17-
├── error.tsx # Error boundary
18-
├── global-error.tsx # Global error boundary
19-
├── loading.tsx # Loading UI
20-
├── not-found.tsx # 404 page
21-
├── favicon.ico # Site favicon
22-
└── sw.js/ # Service worker route handler
23-
```
3+
The portfolio uses Next.js App Router, where file names in [src/app/](../../src/app/) define routes and special behaviors. This follows Next.js convention-based routing rather than explicit route configuration.
4+
5+
## App Router Conventions
6+
7+
**File-Based Routing:** Next.js maps file names to functionality:
8+
9+
- `layout.tsx` — Wraps all child routes with shared UI and metadata
10+
- `page.tsx` — Defines the `/` route content
11+
- `error.tsx` — Catches errors in route segments
12+
- `global-error.tsx` — Catches errors in root layout
13+
- `not-found.tsx` — Handles 404 pages
14+
- `loading.tsx` — Displays while routes load
15+
- `manifest.ts` — Generates PWA manifest `/manifest.webmanifest`
16+
- `robots.ts` — Generates `/robots.txt` for SEO
17+
18+
**Server by Default:** Components in [src/app/](../../src/app/) are React Server Components unless marked with `'use client'`. This minimizes client JavaScript.
2419

25-
## Architecture Pattern
20+
## Component Hierarchy
2621

2722
```mermaid
2823
flowchart TD
@@ -36,276 +31,62 @@ flowchart TD
3631
Page -->|Renders| Banner
3732
Page -->|Renders| Projects[ProjectsGrid]
3833
Page -->|Renders| Pubs[Publications]
39-
Page -->|Initializes| Firebase
40-
Page -->|Registers| SW[Service Worker]
41-
```
42-
43-
## Root Layout
44-
45-
Location: [`src/app/layout.tsx`](../../src/app/layout.tsx)
46-
47-
The root layout defines metadata, global styles, and wraps all pages with the GeneralLayout component.
48-
49-
### Key Features
50-
51-
1. **Metadata Configuration:** SEO, OpenGraph, Twitter Cards, and PWA manifest
52-
2. **Global Styles:** Imports global SCSS styles
53-
3. **Analytics Integration:** Vercel Speed Insights
54-
4. **Service Worker Registration:** Client component for PWA support
55-
5. **Theme Configuration:** Viewport settings and theme color
56-
57-
### Metadata Structure
58-
59-
```typescript
60-
export const metadata: Metadata = {
61-
title: {
62-
template: `%s | ${metadataValues.title}`,
63-
default: metadataValues.title,
64-
},
65-
description: metadataValues.description,
66-
applicationName: metadataValues.title,
67-
referrer: 'origin',
68-
keywords: seoKeywords, // From src/data/keywords.ts
69-
category: 'technology',
70-
authors: [{ name: metadataValues.name, url: metadataValues.url }],
71-
creator: metadataValues.name,
72-
publisher: metadataValues.name,
73-
openGraph: {
74-
/* OpenGraph config */
75-
},
76-
twitter: {
77-
/* Twitter Card config */
78-
},
79-
manifest: '/manifest.webmanifest',
80-
// ... additional metadata
81-
};
82-
```
83-
84-
### Viewport Configuration
85-
86-
```typescript
87-
export const viewport: Viewport = {
88-
themeColor: '#131518',
89-
width: 'device-width',
90-
initialScale: 1,
91-
minimumScale: 1,
92-
maximumScale: 5,
93-
userScalable: true,
94-
};
95-
```
96-
97-
## Home Page
98-
99-
Location: [`src/app/page.tsx`](../../src/app/page.tsx)
100-
101-
The home page is a client component that initializes services and renders main sections.
102-
103-
### Initialization Flow
104-
105-
```mermaid
106-
sequenceDiagram
107-
participant Page
108-
participant Firebase
109-
participant Console
110-
participant SW
111-
participant User
112-
113-
Page->>Firebase: init()
114-
Page->>Console: debounceConsoleLogLogo()
115-
Page->>SW: navigator.serviceWorker.register('/sw.js')
116-
SW-->>Page: Registration complete
117-
Page->>User: Render Banner
118-
Page->>User: Render ProjectsGrid
119-
Page->>User: Render Publications
12034
```
12135

122-
### Component Structure
123-
124-
```typescript
125-
'use client';
126-
127-
export default function Home() {
128-
useEffect(() => {
129-
init(); // Initialize Firebase
130-
debounceConsoleLogLogo(); // Log ASCII art to console
131-
132-
// Register service worker
133-
if (typeof navigator !== 'undefined' && 'serviceWorker' in navigator) {
134-
navigator.serviceWorker.register('/sw.js').catch(function (err) {
135-
console.error('Service Worker registration failed: ', err);
136-
});
137-
}
138-
}, []);
139-
140-
return (
141-
<Box component='div' sx={/* styles */}>
142-
<Banner aria-label='Landing banner' />
143-
<ProjectsGrid aria-label='Grid showing projects worked on' />
144-
<Publications aria-label='List of scientific publications' />
145-
</Box>
146-
);
147-
}
148-
```
36+
The root layout renders GeneralLayout which provides navigation, footer, background, and cookie consent for all pages.
14937

150-
## Special Route Handlers
38+
## Root Layout
15139

152-
### Manifest (`manifest.ts`)
153-
154-
Generates the PWA manifest dynamically:
155-
156-
```typescript
157-
import type { MetadataRoute } from 'next';
158-
159-
export default function manifest(): MetadataRoute.Manifest {
160-
return {
161-
name: "Alexander Sullivan's Portfolio",
162-
short_name: "Alexander Sullivan's Portfolio",
163-
icons: [
164-
{ src: '/icon/android-chrome-192x192.png', sizes: '192x192', type: 'image/png' },
165-
// ... more icons
166-
],
167-
theme_color: '#131518',
168-
background_color: '#131518',
169-
display: 'standalone',
170-
start_url: '/',
171-
};
172-
}
173-
```
40+
**Metadata Configuration:** The layout exports a metadata object with SEO tags, OpenGraph, Twitter Cards, and PWA manifest path. Keywords are imported from [src/data/keywords.ts](../../src/data/keywords.ts).
17441

175-
### Robots (`robots.ts`)
42+
**Viewport Setup:** Defines theme color (#131518), responsive scaling, and device width settings for mobile browsers.
17643

177-
Generates robots.txt for SEO:
44+
**GeneralLayout:** Wraps children with [GeneralLayout](../../src/layouts/GeneralLayout.tsx) which provides navigation, footer, stars background, and cookie consent.
17845

179-
```typescript
180-
import type { MetadataRoute } from 'next';
46+
**Global Styles:** Imports [globals.scss](../../src/styles/globals.scss) for application-wide CSS.
18147

182-
export default function robots(): MetadataRoute.Robots {
183-
return {
184-
rules: {
185-
userAgent: '*',
186-
allow: '/',
187-
},
188-
sitemap: 'https://alexjsully.me/sitemap.xml',
189-
};
190-
}
191-
```
48+
**Analytics:** Includes Vercel SpeedInsights for performance tracking.
19249

193-
## Error Handling
50+
Implementation: [src/app/layout.tsx](../../src/app/layout.tsx)
19451

195-
### Error Boundary (`error.tsx`)
196-
197-
Catches errors in the app and displays a fallback UI:
198-
199-
```typescript
200-
'use client';
201-
202-
export default function Error({
203-
error,
204-
reset,
205-
}: {
206-
error: Error & { digest?: string };
207-
reset: () => void;
208-
}) {
209-
return (
210-
<div>
211-
<h2>Something went wrong!</h2>
212-
<button onClick={() => reset()}>Try again</button>
213-
</div>
214-
);
215-
}
216-
```
52+
## Home Page
21753

218-
### Global Error Boundary (`global-error.tsx`)
219-
220-
Catches errors at the root level (even in layout):
221-
222-
```typescript
223-
'use client';
224-
225-
export default function GlobalError({
226-
error,
227-
reset,
228-
}: {
229-
error: Error & { digest?: string };
230-
reset: () => void;
231-
}) {
232-
return (
233-
<html>
234-
<body>
235-
<h2>Something went wrong!</h2>
236-
<button onClick={() => reset()}>Try again</button>
237-
</body>
238-
</html>
239-
);
240-
}
241-
```
54+
The home page ([src/app/page.tsx](../../src/app/page.tsx)) is a client component (`'use client'`) that initializes services on mount:
24255

243-
## Loading States
56+
**Firebase Initialization:** Calls `init()` from [src/configs/firebase.ts](../../src/configs/firebase.ts) to start analytics and performance tracking.
24457

245-
Location: [`src/app/loading.tsx`](../../src/app/loading.tsx)
58+
**Console Logo:** Debounced ASCII art logged to browser console via [ascii helper](../../src/helpers/ascii.ts).
24659

247-
Displays a loading UI while the page is being rendered:
60+
**Service Worker Registration:** Registers `/sw.js` for PWA offline support. Registration runs once on page load.
24861

249-
```typescript
250-
import { CircularProgress } from '@mui/material';
62+
**Content Rendering:** Displays Banner, ProjectsGrid, and Publications components in vertical stack.
25163

252-
export default function Loading() {
253-
return (
254-
<div style={centeredContainerStyles}>
255-
<CircularProgress />
256-
</div>
257-
);
258-
}
259-
```
64+
Implementation: [src/app/page.tsx](../../src/app/page.tsx)
26065

261-
The container uses inline styles with flexbox centering: `display: 'flex'`, `justifyContent: 'center'`, and `padding: '2rem'`.
66+
## Special Route Handlers
26267

263-
## 404 Not Found
68+
**PWA Manifest** ([src/app/manifest.ts](../../src/app/manifest.ts)) — Generates `/manifest.webmanifest` with app name, icons, theme colors, and display mode. See [PWA Documentation](./pwa.md).
26469

265-
Location: [`src/app/not-found.tsx`](../../src/app/not-found.tsx)
70+
**Robots.txt** ([src/app/robots.ts](../../src/app/robots.ts)) — Generates `/robots.txt` allowing all crawlers with sitemap URL for SEO.
26671

267-
Custom 404 page with navigation back to home:
72+
## Error Handling
26873

269-
```typescript
270-
export default function NotFound() {
271-
const pathname = usePathname();
74+
**Error Boundary** ([src/app/error.tsx](../../src/app/error.tsx)) — Catches errors in route segments and displays fallback UI with reset button.
27275

273-
return (
274-
<Stack /* ... */>
275-
<Typography>404</Typography>
276-
<Typography>{pathname}?! What is that?!</Typography>
277-
<Link href='/' aria-label='Go home'>
278-
<Button>Go back home!</Button>
279-
</Link>
280-
</Stack>
281-
);
282-
}
283-
```
76+
**Global Error** ([src/app/global-error.tsx](../../src/app/global-error.tsx)) — Catches errors in root layout, including its own `<html>` and `<body>` tags since layout errors prevent normal rendering.
28477

285-
## Best Practices
78+
Both error boundaries are client components that accept `error` and `reset` props.
28679

287-
1. **Server vs Client Components:** Use server components by default, mark client components with `'use client'`
288-
2. **Metadata:** Define metadata in layout.tsx for SEO benefits
289-
3. **Error Boundaries:** Implement error.tsx for graceful error handling
290-
4. **Loading States:** Use loading.tsx for better UX during navigation
291-
5. **TypeScript:** Use Next.js types like `MetadataRoute`, `Metadata`, and `Viewport`
292-
6. **Accessibility:** Include proper ARIA labels on all components
80+
## Loading & 404
29381

294-
## Testing
82+
**Loading UI** ([src/app/loading.tsx](../../src/app/loading.tsx)) — Shows MUI CircularProgress spinner centered on screen while routes load.
29583

296-
Test files are located alongside their components:
84+
**Not Found** ([src/app/not-found.tsx](../../src/app/not-found.tsx)) — Custom 404 page displaying pathname and navigation button back to home.
29785

298-
- `loading.test.tsx` - Tests loading component
299-
- `not-found.test.tsx` - Tests 404 page
86+
Implementation: [src/app/loading.tsx](../../src/app/loading.tsx), [src/app/not-found.tsx](../../src/app/not-found.tsx)
30087

30188
## Related Documentation
30289

303-
- [Architecture Overview](./index.md)
304-
- [Layouts](./layouts.md)
305-
- [Components](./components/index.md)
306-
- [PWA Documentation](./pwa.md)
307-
- [Next.js App Router Documentation](https://nextjs.org/docs/app)
308-
309-
---
310-
311-
💡 **Tip:** The App Router automatically handles routing based on the file structure. Any `page.tsx` file becomes a route, and `layout.tsx` files wrap their children routes.
90+
- [Architecture Overview](./index.md) — System architecture
91+
- [Layouts Documentation](./layouts.md) — GeneralLayout details
92+
- [PWA Documentation](./pwa.md) — Service worker and manifest

0 commit comments

Comments
 (0)