# second-brain

**Repository Path**: GQ-hh/second-brain

## Basic Information

- **Project Name**: second-brain
- **Description**: No description available
- **Primary Language**: NodeJS
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-14
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BookBrain MVP

Minimal reading-notes MVP with:
- React + Vite frontend
- FastAPI + SQLAlchemy backend
- PostgreSQL via Docker Compose

Core flows currently implemented:
- register and login
- create and manage books
- write notes
- ask book-specific questions
- search notes within the current book
- configure model provider settings on a dedicated page

## Project Structure

```text
backend/
  app/
  tests/
frontend/
docs/
docker-compose.yml
```

## Run Locally

```bash
docker compose up --build
```

Services:
- frontend: `http://localhost:3000`
- backend: `http://localhost:8000`
- health check: `http://localhost:8000/health`

## Frontend Navigation

Authenticated app routes:
- `/workspace`: main note-taking and Q&A workspace
- `/settings/model`: dedicated model configuration page

Routing behavior:
- unauthenticated users see the auth panel
- unknown authenticated routes redirect to `/workspace`

## Workspace UX

The main workspace is split into:
- `Record`: primary note entry area
- `Ask`: primary Q&A area for the selected book
- `Timeline`: recent notes and answers for the selected book

Search is not embedded inline anymore:
- search opens from the workspace header
- results appear in a right-side drawer
- the drawer is closed by default

## Sidebar UX

The sidebar now supports:
- collapse and expand
- persisted collapsed state in local storage
- book selection
- book creation
- per-book management actions

Per-book actions:
- rename
- edit author
- delete

Settings entry:
- `Model Settings` lives in the sidebar and navigates to `/settings/model`

## Model Settings

The model settings page supports:
- provider
- chat model
- API key
- optional base URL

Behavior notes:
- existing API keys are not echoed back into the form
- saving with an empty API key clears the stored key
- load and save flows include stale-request guards to avoid post-unmount state writes

## Backend API

Existing core endpoints:
- `POST /api/auth/register`
- `POST /api/auth/login`
- `GET /api/me/llm-config`
- `PUT /api/me/llm-config`
- `GET /api/books`
- `POST /api/books`
- `GET /api/books/{book_id}/notes`
- `POST /api/books/{book_id}/notes`
- `POST /api/books/{book_id}/ask`

New book-management endpoints:
- `PUT /api/books/{book_id}`
  - updates `title` and `author` for a book owned by the current user
  - trims input before persistence
  - returns `404` when the book is not owned by the current user or does not exist
  - returns `422` if the trimmed title is empty
- `DELETE /api/books/{book_id}`
  - deletes a book owned by the current user
  - returns `204 No Content` on success
  - returns `404` when the book is not owned by the current user or does not exist

## Testing

Backend test files:
- `backend/tests/test_mvp_flow.py`
- `backend/tests/test_book_management_api.py`

Typical commands:

```bash
pytest -q backend/tests/test_mvp_flow.py
pytest -q backend/tests/test_book_management_api.py
pytest -v backend
```

Frontend verification:

```bash
cd frontend
npm run build
```

## LLM Fallback

If no LLM API key is configured:
- the ask flow uses the local fallback path
- the end-to-end Q&A flow still remains usable