Skip to content

Commit 39e962b

Browse files
rahim-jrrahim-jr
committed
feat: add comprehensive documentation for project setup, architecture, and troubleshooting
1 parent 8a415d1 commit 39e962b

File tree

9 files changed

+595
-10
lines changed

9 files changed

+595
-10
lines changed

‎client/README.md‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -13,16 +13,15 @@ Visit [http://localhost:3000](http://localhost:3000)
1313

1414
## Documentation
1515

16-
All documentation has been moved to the [`docs/`](./docs/) folder:
17-
18-
- **[Quick Start Guide](./docs/QUICKSTART.md)** - Get up and running in 3 steps
19-
- **[README](./docs/README.md)** - Full project documentation
20-
- **[Migration Guide](./docs/MIGRATION.md)** - Vite to Next.js migration details
21-
- **[Upgrade Steps](./docs/UPGRADE_STEPS.md)** - Step-by-step upgrade instructions
22-
- **[Architecture Overview](./docs/ARCHITECTURE.md)** - Before/after architecture comparison
23-
- **[Migration Summary](./docs/MIGRATION_SUMMARY.md)** - Technical migration details
24-
- **[Migration Complete](./docs/MIGRATION_COMPLETE.md)** - Migration completion checklist
25-
- **[Verification Checklist](./docs/VERIFICATION_CHECKLIST.md)** - Testing checklist
16+
Project documentation is in the shared root [`docs/`](../docs/) folder:
17+
18+
- **[Docs Home](../docs/README.md)**
19+
- **[Quick Start](../docs/QUICKSTART.md)**
20+
- **[Product Guide](../docs/PRODUCT_GUIDE.md)**
21+
- **[Architecture](../docs/ARCHITECTURE.md)**
22+
- **[Technical Reference](../docs/TECHNICAL_REFERENCE.md)**
23+
- **[Engineering Practices](../docs/ENGINEERING_PRACTICES.md)**
24+
- **[Troubleshooting](../docs/TROUBLESHOOTING.md)**
2625

2726
## Tech Stack
2827

‎docs/ARCHITECTURE.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Architecture
2+
3+
## High-Level System
4+
5+
```mermaid
6+
flowchart LR
7+
U[Browser] --> C[Next.js Client App]
8+
C --> SA[Next.js Server Actions]
9+
SA --> GH[GitHub REST + GraphQL APIs]
10+
C --> OA[Express OAuth Service]
11+
OA --> GHO[GitHub OAuth Endpoints]
12+
```
13+
14+
## Services
15+
16+
### Frontend (`client/`)
17+
18+
- Framework: Next.js App Router + React
19+
- Responsibilities:
20+
- UI rendering
21+
- Auth flow initiation and callback handling
22+
- Server actions for GitHub data read/write
23+
- Route protection via middleware
24+
25+
### OAuth Service (`server/`)
26+
27+
- Framework: Express
28+
- Responsibilities:
29+
- Return safe OAuth config (`/api/auth/config`)
30+
- Exchange OAuth code for token (`/api/auth/exchange`)
31+
- Fetch GitHub user profile during exchange
32+
33+
## Authentication Flow
34+
35+
```mermaid
36+
sequenceDiagram
37+
participant B as Browser
38+
participant N as Next.js Client
39+
participant S as Express OAuth Server
40+
participant G as GitHub
41+
42+
B->>N: Click "Sign in with GitHub"
43+
N->>S: GET /api/auth/config
44+
S-->>N: client_id, redirect_uri
45+
N->>G: Redirect to /login/oauth/authorize (PKCE + state)
46+
G-->>B: Redirect to /auth/callback?code=...&state=...
47+
B->>N: Load callback page
48+
N->>S: POST /api/auth/exchange (code, verifier)
49+
S->>G: Exchange code for token
50+
S->>G: Fetch /user
51+
S-->>N: access_token + user
52+
N->>N: Set httpOnly auth cookie via server action
53+
N-->>B: Redirect to /workspace
54+
```
55+
56+
## Runtime Request Patterns
57+
58+
### Read Path
59+
60+
1. UI component calls server action in `client/app/actions/github.ts`
61+
2. Action calls `githubReadJson` (`client/lib/github/server.ts`)
62+
3. Wrapper adds GitHub auth headers and caching policy
63+
4. Response is mapped to app types in `client/lib/github/mappers.ts`
64+
5. UI renders normalized data
65+
66+
### Write Path
67+
68+
1. UI component calls server action in `client/app/actions/issues.ts`
69+
2. Action calls `githubWriteJson` with no-store cache
70+
3. On success, action calls `revalidateTag('github')`
71+
4. Updated entity is returned and local UI state is patched
72+
73+
### Linked Pull Request Lookup
74+
75+
- Issue list batches lookups by repository
76+
- GraphQL query uses `issueOrPullRequest(number: ...)`
77+
- Non-issue nodes are ignored to avoid failures on PR numbers
78+
79+
## Caching Model
80+
81+
- Read calls default to `revalidate: 60` seconds and tag `github`
82+
- Write calls are always `no-store`
83+
- Mutations trigger cache invalidation via `revalidateTag('github')`
84+
85+
## Route Segmentation
86+
87+
- Public routes: `client/app/(public)/...`
88+
- Authenticated workspace: `client/app/(auth)/...`
89+
- Middleware enforces token presence for `/workspace`
90+
91+
## Error Handling
92+
93+
- Client actions normalize user-facing messages with `getErrorMessage`
94+
- Errors are reported through `reportClientError` telemetry utility
95+
- Workspace has dedicated `loading` and `error` boundaries
96+
97+
## Security Notes
98+
99+
- Access token stored in `httpOnly` cookie
100+
- OAuth `state` and PKCE verifier validated on callback
101+
- Session reset route clears auth cookies and performs safe redirect
102+
- OAuth server validates redirect URI mismatch attempts

‎docs/ENGINEERING_PRACTICES.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Engineering Practices
2+
3+
## Engineering Principles
4+
5+
- Favor clarity over cleverness.
6+
- Keep side effects isolated.
7+
- Prefer typed boundaries between layers.
8+
- Keep UI, API wrapper, and mapper responsibilities separate.
9+
10+
## Branch and PR Workflow
11+
12+
1. Create a focused feature branch.
13+
2. Keep PR scope small and reviewable.
14+
3. Include problem statement and validation steps in PR description.
15+
4. Update docs in the same PR when behavior changes.
16+
17+
## Code Quality Standards
18+
19+
- TypeScript strict mode is enabled in both services.
20+
- Preserve file/module boundaries:
21+
- UI components do not call raw GitHub APIs directly.
22+
- Server actions orchestrate read/write operations.
23+
- Mapping layer normalizes external payloads.
24+
- Handle async failures with explicit error messages and telemetry hooks.
25+
26+
## Validation Before Merge
27+
28+
Minimum local checks:
29+
30+
```bash
31+
# Client
32+
cd client
33+
npx tsc --noEmit
34+
35+
# Server
36+
cd ../server
37+
npx tsc --noEmit
38+
```
39+
40+
Optional checks:
41+
42+
- `client`: `npm run lint` (requires ESLint setup in this repo)
43+
- `server`: `npm run lint` (if lint config is present)
44+
45+
## Documentation Standards
46+
47+
- Every docs page should include:
48+
- clear purpose
49+
- expected audience
50+
- concrete steps or references
51+
- Avoid stale references; verify paths and commands.
52+
- Prefer examples with real repo paths and routes.
53+
54+
## Change Management Checklist
55+
56+
When changing behavior, verify if updates are needed in:
57+
58+
- `docs/QUICKSTART.md`
59+
- `docs/ARCHITECTURE.md`
60+
- `docs/TECHNICAL_REFERENCE.md`
61+
- `docs/TROUBLESHOOTING.md`
62+
63+
## Security and Privacy Checklist
64+
65+
- Never commit secrets (`.env`, access tokens).
66+
- Keep tokens in server-managed cookies only.
67+
- Validate redirect URIs and OAuth state.
68+
- Avoid exposing internal errors directly in user-facing messages.
69+

‎docs/PRODUCT_GUIDE.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Product Guide
2+
3+
## What This Project Is
4+
5+
NesOHQ Issue Tracker is a web workspace for managing GitHub issues across repositories from one interface.
6+
7+
It focuses on:
8+
9+
- Fast issue discovery
10+
- Lightweight editing
11+
- Clear context (labels, assignees, linked pull requests)
12+
13+
## Core User Workflows
14+
15+
### 1. Sign In
16+
17+
- User clicks GitHub sign-in.
18+
- User completes OAuth consent on GitHub.
19+
- User returns to workspace with authenticated session.
20+
21+
### 2. Browse Repositories
22+
23+
- Sidebar lists accessible repositories.
24+
- User can search repositories.
25+
- User can pin frequently used repositories.
26+
27+
### 3. Find Issues
28+
29+
- Filter by issue state (`open`, `closed`, `all`)
30+
- Search issues by query
31+
- Load additional pages of results
32+
33+
### 4. Create a New Issue
34+
35+
- Choose repository
36+
- Enter title and body (markdown supported)
37+
- Apply labels
38+
- Submit issue to GitHub
39+
40+
### 5. Update an Existing Issue
41+
42+
- Edit title
43+
- Edit description/body
44+
- Toggle labels
45+
- Close/Reopen issue
46+
47+
### 6. Review Linked Pull Requests
48+
49+
Linked PR statuses are shown with clear visual state:
50+
51+
- Open or new: green
52+
- Failed (closed without merge): red
53+
- Merged: purple
54+
55+
## Permission Model
56+
57+
The app uses the signed-in GitHub user's token. All visible repositories and writable actions are constrained by that user's GitHub permissions.
58+
59+
## Current Feature Boundaries
60+
61+
- Assignees are currently display-only (no assign/unassign control in UI)
62+
- No custom issue templates
63+
- No built-in analytics dashboard in this repo (client telemetry hooks exist)
64+
65+
## Primary Value
66+
67+
- Reduce context switching between repositories
68+
- Keep issue triage and updates fast
69+
- Provide a consistent editing experience over GitHub issue APIs

‎docs/QUICKSTART.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Quickstart
2+
3+
This guide gets the full stack running locally:
4+
5+
- Next.js frontend (`client`, port `3000`)
6+
- Express OAuth service (`server`, port `3001`)
7+
8+
## Prerequisites
9+
10+
- Node.js `22.x`
11+
- npm `10+`
12+
- A GitHub OAuth App (for login flow)
13+
14+
## 1. Configure Environment Variables
15+
16+
### Server
17+
18+
Copy the template:
19+
20+
```bash
21+
cp server/.env.example server/.env
22+
```
23+
24+
Set required values in `server/.env`:
25+
26+
- `GH_CLIENT_ID`
27+
- `GH_CLIENT_SECRET`
28+
29+
Optional but recommended:
30+
31+
- `GH_REDIRECT_URI=http://localhost:3000/auth/callback`
32+
- `CORS_ORIGIN=http://localhost:3000`
33+
34+
### Client
35+
36+
Copy the template:
37+
38+
```bash
39+
cp client/.env.local.example client/.env.local
40+
```
41+
42+
Set:
43+
44+
- `NEXT_PUBLIC_API_URL=http://localhost:3001`
45+
46+
## 2. Install Dependencies
47+
48+
```bash
49+
cd server && npm install
50+
cd ../client && npm install
51+
```
52+
53+
## 3. Start Services
54+
55+
Run in two terminals:
56+
57+
Terminal 1:
58+
59+
```bash
60+
cd server
61+
npm run dev
62+
```
63+
64+
Terminal 2:
65+
66+
```bash
67+
cd client
68+
npm run dev
69+
```
70+
71+
Open: `http://localhost:3000`
72+
73+
## 4. Smoke Test Checklist
74+
75+
1. Home page renders sign-in UI.
76+
2. Click `Sign in with GitHub`.
77+
3. OAuth callback returns to `/auth/callback`.
78+
4. You are redirected to `/workspace`.
79+
5. Repositories and issues load.
80+
6. Create or edit an issue to verify write path.
81+
82+
## Common Setup Notes
83+
84+
- If sign-in fails immediately, verify `GH_CLIENT_ID` and `GH_CLIENT_SECRET`.
85+
- If callback fails, verify OAuth app callback URL and `GH_REDIRECT_URI` alignment.
86+
- If `/api` calls fail with CORS errors, set `CORS_ORIGIN` to frontend origin.
87+
- `client/public/config.js` can override API base URL at runtime for deployed builds.
88+

0 commit comments

Comments
 (0)