Skip to content

testing #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion src/content/_meta.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,22 @@
const meta = {
index: "Getting Started",
index: 'Getting Started',

// guides: {
// title: 'Guides',
// collapsed: false,
// order: 1,
// },

// reference: {
// title: 'Reference',
// collapsed: false,
// order: 2,
// },

// architecture: {
// title: 'Architecture',
// order: 3,
// },
};

export default meta;
5 changes: 5 additions & 0 deletions src/content/architecture/_meta.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
const meta = {
index: "Architecture",
};

export default meta;
69 changes: 69 additions & 0 deletions src/content/architecture/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
---
title: "System Architecture"
description: "A high-level overview of how the front-end, API routes and third-party services fit together."
---

import { Mermaid, Callout } from 'nextra/components'

# System Architecture

The project consists of **three main layers**:

1. **Front-end** – a Next.js App Router application rendered on the edge.
2. **API routes** – collocated inside <code>app/api/*</code>, exposing server-less endpoints.
3. **Third-party services** – OpenAI, Vercel KV and Pagefind for search.

---

## Component diagram

<Mermaid chart={`flowchart LR
subgraph Client
A[Browser] -- HTTP --> B[Next.js App]
end
subgraph Serverless
B --> C[API Route – /api/chat]
B --> D[API Route – /api/image]
B --> E[API Route – /api/articles/*]
end
subgraph OpenAI
F[(Chat Completion)]
G[(Embeddings)]
H[(TTS)]
end
C -- Web-Stream --> F
D --> H
E --> G
style A fill:#46f488,color:#fff
style B fill:#d06bee,color:#fff
style C fill:#fa7b6a,color:#fff
style D fill:#fa7b6a,color:#fff
style E fill:#fa7b6a,color:#fff
style F fill:#000,color:#46f488
style G fill:#000,color:#46f488
style H fill:#000,color:#46f488
`} />

---

## Data flow (user asks a question in the chat widget)

1. **Message mutation** – The React chat widget POSTs the message to **`/api/chat`**.
2. **Tool-enabled streaming** – The API route uses <code>@ai-sdk/openai</code> to stream chunks back.
3. **UI hydration** – The front-end consumes the stream with Server Sent Events and updates the UI in real time.

---

<Callout type="tip">The entire round-trip is <strong>edge-optimised</strong> – everything happens close to the user for low latency.</Callout>

---

## Where to look next

| Path | What you will find |
| -------------------------- | ----------------------------------------------- |
| <code>app/api/chat/</code> | Streaming AI completions with tools |
| <code>app/api/articles/*</code> | Vector store ingest & search |
| <code>components/chat/</code> | Front-end chat widget with tool rendering |

This should give you enough pointers to dive into the code with confidence.
8 changes: 8 additions & 0 deletions src/content/guides/_meta.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
const meta = {
// index: "Guides",
// quickstart: "Quickstart",
// "documentation-authoring": "Documentation Authoring",
// contributing: "Contributing",
};

export default meta;
59 changes: 59 additions & 0 deletions src/content/guides/contributing.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
title: "Contributing"
description: "Guidelines for reporting issues, adding new features or improving the documentation."
---

import { Callout } from 'nextra/components'

# Contributing

We :heart: contributions! Whether it is a **bug report**, a **new feature** or an improvement to the **documentation**, your help makes the project better for everyone.

---

## 1&nbsp;· Find something to work on

1. Browse the **Issues** tab and filter by the `good first issue` or `documentation` labels.
2. Join the discussion to avoid duplicate work.

<Callout type="tip">If you are unsure, open a **Draft PR** early – reviewers can then give feedback as you iterate.</Callout>

---

## 2&nbsp;· Fork & create a branch

```bash
git checkout -b feat/my-awesome-thing
```

Use **present-tense imperative** commit messages – e.g. _"Add solar panel power graph"_.

---

## 3&nbsp;· Run the checks locally

```bash
pnpm lint # ESLint, TypeScript & MDX
pnpm test # unit tests (if any)
pnpm build # type errors & static site build
```

The CI pipeline runs the same commands – make them pass locally to save round-trips.

---

## 4&nbsp;· Open the pull request

The PR template will ask you to confirm:

• The code builds.
• New docs include front-matter.
• Screenshots / GIFs for UI changes are attached.

Reviewers strive to respond within **48&nbsp;hours**. Feel free to ping after that.

---

## 5&nbsp;· Celebrate 🎉

Your changes will land in `main` once approvals are in and checks are green. Thank you for investing your time!
99 changes: 99 additions & 0 deletions src/content/guides/documentation-authoring.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
---
title: "Documentation Authoring"
description: "Write, organise and publish MDX pages using Nextra."
---

import { Callout } from "nextra/components";

# Documentation Authoring

<Callout type="info">
If you prefer a deep-dive, open `deep-wiki/MARKDOWN_AUTHORING_GUIDE.md`. The
following is an opinionated **cheat-sheet** that covers 80&nbsp;% of
day-to-day cases.
</Callout>

---

## File location

• All docs live in **`deep-wiki/src/content/`**.
• Folders and filenames map 1-to-1 to the URL.

```text
src/content/
└─ guides/
└─ quickstart.mdx → /guides/quickstart
```

---

## Front-matter template

```mdx
---
title: "My Page Title"
description: "One-sentence meta description (max ~160 chars)."
---
```

`title` and `description` are **mandatory** – the CI fails otherwise.

Optional extras:

| Key | What it does |
| -------------- | ----------------------------------------- |
| `sidebarTitle` | Short label in the sidebar |
| `toc` | `false` hides the table of contents |
| `asIndexPage` | Marks the file as the folder landing page |

---

## Update the sidebar (`_meta.ts`)

Each folder has its own `_meta.ts` – update or create it:

```ts
const meta = {
index: "Overview",
quickstart: "Quickstart",
"documentation-authoring": "Documentation Authoring",
};

export default meta;
```

Not in the list? → Nextra will show the page **alphabetically at the bottom**.

---

## Built-in components

| Component | Use-case | Example |
| --------- | ------------------------- | ------------------------------------ |
| `Callout` | Tips, warnings | `<Callout type="tip">…</Callout>` |
| `Steps` | Multi-step walkthroughs | `<Steps>### One … ### Two …</Steps>` |
| `Tabs` | Code in npm / pnpm / yarn | `npm2yarn` |

All components are tree-shaken by Next.js and add **zero client-side JS** unless needed.

---

## Preview locally

```bash
pnpm dev # http://localhost:3000/docs
```

Hot re-load applies to both code **and** docs.

---

## Pull request checklist

1. CI passes (`pnpm lint && pnpm build`).
2. Exactly one `# H1` per file, no orphan `###` headings.
3. No lines > 120&nbsp;chars outside code blocks.
4. Every new page added to `_meta.ts`.

Happy writing! ✨
28 changes: 28 additions & 0 deletions src/content/guides/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
title: "Guides"
description: "Step-by-step tutorials that teach you how to work with the codebase and contribute to the project."
asIndexPage: true
---

import { Steps, Callout } from 'nextra/components'

# Guides

This section is **task-oriented** – each article walks you through a specific activity such as spinning up the project for the first time, authoring new documentation, or submitting a pull request.

<Callout type="info">If you are completely new to the codebase start with <strong>Quickstart</strong>.</Callout>

<Steps>
### Quickstart
Clone the repo, install dependencies and run the development server locally.

### Documentation Authoring
Learn the MDX conventions and how to make your page appear in the sidebar.

### Contributing
Open a ticket, create a branch and raise a pull-request – our quality checklist in detail.
</Steps>

---

Select a guide from the sidebar to get started ➡️
85 changes: 85 additions & 0 deletions src/content/guides/quickstart.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
---
title: "Quickstart"
description: "Zero-to-running in less than five minutes."
---

import { Steps, Callout } from "nextra/components";

# Quickstart

These instructions assume **macOS / Linux**.
Windows users can follow the same steps inside **WSL&nbsp;2**.

---

## 1&nbsp;· Clone & install dependencies

```bash
git clone <your-fork-url>
cd <project-root>
pnpm install
```

---

## 2&nbsp;· Environment variables

```bash
cp .env.example .env
# then open .env and fill in the missing secrets
```

At minimum you will need valid **OpenAI** keys if you intend to test the AI features locally.

---

## 3&nbsp;· Start the dev server

```bash
pnpm dev
```

Output should end with something like:

```text
ready - started server on 0.0.0.0:3000, url: http://localhost:3000
```

• **Main app:** [http://localhost:3000](http://localhost:3000)
• **Docs site:** [http://localhost:3000/docs](http://localhost:3000/docs)

<Callout type="tip">
Both apps run in the same Next.js instance – there is no need to launch two
separate processes.
</Callout>

---

## 4&nbsp;· Common dev commands

| Command | Purpose |
| ------------ | ----------------------------------- |
| `pnpm dev` | Hot-reloading development server |
| `pnpm build` | Production build (app **and** docs) |
| `pnpm lint` | TypeScript, ESLint & MDX checks |
| `pnpm test` | Jest / vitest (if present) |

---

## 5&nbsp;· Next steps

<Steps>
### Play with components
Open <code>components/</code> and tweak something – the browser auto reloads.

### Explore the API routes

Visit `/api/iss` in the browser – you should see live JSON from the International Space Station.

### Add a new documentation page

Follow the **Documentation Authoring** guide → create `src/content/my-page.mdx` → refresh `/docs`.

</Steps>

You are now set! 🚀
Loading