Skip to content

Commit 6dcbc73

Browse files
farce1farce1
committed
Add comprehensive README and CONTRIBUTING guide
Rewrite README with hero section, badges, feature overview, quick start, tech stack, project structure, roadmap, and contributing summary. Add CONTRIBUTING.md with setup instructions, dev commands, code guidelines, and contribution workflow.
1 parent e2b67f3 commit 6dcbc73

2 files changed

Lines changed: 276 additions & 4 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Contributing to openNotes
2+
3+
Thanks for your interest in contributing! Whether it's a bug fix, new feature, translation, or documentation improvement — every contribution helps.
4+
5+
## Getting Started
6+
7+
### Prerequisites
8+
9+
| Tool | Version | Install |
10+
|---|---|---|
11+
| [Node.js](https://nodejs.org) | LTS | [Download](https://nodejs.org) |
12+
| [Rust](https://rustup.rs) | Stable | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` |
13+
| [Bun](https://bun.sh) | Latest | `curl -fsSL https://bun.sh/install \| bash` |
14+
| [Ollama](https://ollama.com) | Latest | [Download](https://ollama.com/download) |
15+
16+
### Setup
17+
18+
```bash
19+
git clone https://github.com/farce1/opennotes.git
20+
cd opennotes
21+
bun install --frozen-lockfile
22+
bun run tauri dev
23+
```
24+
25+
On first launch the app will prompt you to download the transcription models (~1 GB). Ollama must be running for summarization to work.
26+
27+
## Development
28+
29+
### Commands
30+
31+
| Command | Description |
32+
|---|---|
33+
| `bun run tauri dev` | Run the full app in development mode |
34+
| `bun run dev` | Frontend only (Vite dev server on port 1420) |
35+
| `bun run build` | TypeScript check + Vite production build |
36+
| `bun run test` | Run frontend tests (Vitest) |
37+
| `bun run tauri build` | Build native installers |
38+
| `cd src-tauri && cargo test` | Run Rust backend tests |
39+
| `cd src-tauri && cargo clippy` | Lint Rust code |
40+
41+
### Project Layout
42+
43+
```
44+
src/ → React frontend (TypeScript)
45+
components/ → UI components
46+
views/ → Page-level views
47+
hooks/ → Custom React hooks
48+
contexts/ → React context providers
49+
lib/ → Utilities (db, export, settings)
50+
i18n/locales/ → Translations (en, pl)
51+
52+
src-tauri/ → Rust backend
53+
src/ → Core modules (audio, transcription, session, llm)
54+
migrations/ → SQLite schema migrations
55+
```
56+
57+
### Tech Stack at a Glance
58+
59+
- **Frontend:** React 19 + TypeScript + Tailwind CSS 4 + Vite 7
60+
- **Backend:** Rust + Tauri 2 + SQLite (SQLx)
61+
- **Audio:** cpal + libopusenc
62+
- **Transcription:** sherpa-rs (Silero VAD + Parakeet TDT)
63+
- **Summarization:** Ollama (local LLM)
64+
65+
## How to Contribute
66+
67+
### Reporting Bugs
68+
69+
Open an [issue](https://github.com/farce1/opennotes/issues/new) with:
70+
71+
- Steps to reproduce
72+
- Expected vs actual behavior
73+
- OS and app version
74+
- Relevant logs (if any)
75+
76+
### Suggesting Features
77+
78+
Open an [issue](https://github.com/farce1/opennotes/issues/new) describing:
79+
80+
- The problem you're trying to solve
81+
- Your proposed solution
82+
- Any alternatives you've considered
83+
84+
### Submitting Code
85+
86+
1. **Fork** the repository
87+
2. **Create a branch** from `main`:
88+
```bash
89+
git checkout -b feature/my-feature
90+
```
91+
3. **Make your changes** — keep commits focused and atomic
92+
4. **Test your changes:**
93+
```bash
94+
bun run test
95+
cd src-tauri && cargo test && cargo clippy
96+
```
97+
5. **Push** and open a **Pull Request** against `main`
98+
99+
For larger changes, please open an issue first so we can discuss the approach before you invest significant effort.
100+
101+
### Adding Translations
102+
103+
Translations live in `src/i18n/locales/`. To add a new language:
104+
105+
1. Copy `src/i18n/locales/en/` to a new folder (e.g., `de/` for German)
106+
2. Translate the JSON values (keep the keys unchanged)
107+
3. Register the new locale in the i18n config
108+
4. Add the language option to the settings UI
109+
110+
## Code Guidelines
111+
112+
- **TypeScript** — strict mode is enabled; no `any` unless absolutely necessary
113+
- **Rust** — code must pass `cargo clippy` without warnings
114+
- **Components** — use the design-system dropdown (`src/components/ui/Dropdown.tsx`) instead of native `<select>` elements
115+
- **Styling** — Tailwind CSS utility classes; avoid inline styles
116+
- **Commits** — write clear, concise commit messages describing *what* and *why*
117+
118+
## License
119+
120+
By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

‎README.md‎

Lines changed: 156 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,157 @@
1-
# opennotes
2-
Open-Source AI Meeting Notes Local-first meeting transcription and summarization. No cloud. No bots. No cost.
1+
<p align="center">
2+
<img src="src-tauri/icons/128x128@2x.png" width="128" height="128" alt="openNotes logo" />
3+
</p>
34

4-
## UI Design Rules
5-
- Do not use native HTML `<select>` controls in app UI. Use the design-system dropdown component (`src/components/ui/Dropdown.tsx`) so controls match the product style.
5+
<h1 align="center">openNotes</h1>
6+
7+
<p align="center">
8+
<strong>One-click meeting notes. Local-first. Free forever.</strong>
9+
</p>
10+
11+
<p align="center">
12+
Record, transcribe, and summarize your meetings — entirely on your machine.<br />
13+
No cloud. No bots. No subscriptions. No data leaves your device.
14+
</p>
15+
16+
<p align="center">
17+
<a href="https://github.com/farce1/opennotes/actions/workflows/ci.yml"><img src="https://github.com/farce1/opennotes/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
18+
<a href="https://github.com/farce1/opennotes/releases/latest"><img src="https://img.shields.io/github/v/release/farce1/opennotes?color=blue&label=latest" alt="Latest Release" /></a>
19+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License" /></a>
20+
<img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey" alt="Platforms" />
21+
</p>
22+
23+
---
24+
25+
<!-- TODO: Replace with actual screenshot or demo GIF -->
26+
<!-- <p align="center">
27+
<img src="docs/demo.gif" width="720" alt="openNotes demo" />
28+
</p> -->
29+
30+
## Why openNotes?
31+
32+
Most meeting tools send your audio to the cloud, charge monthly fees, and drop bots into your calls. **openNotes does none of that.**
33+
34+
- **Private by design** — All transcription and summarization run on your hardware. Zero network calls for processing.
35+
- **Truly free** — Open-source under MIT. No tiers, no trials, no limits.
36+
- **One-click workflow** — Hit record, finish your meeting, get structured notes. That's it.
37+
38+
## Features
39+
40+
**Recording**
41+
- Capture microphone + system audio simultaneously
42+
- Floating widget overlay — control recordings without leaving your meeting
43+
- Global shortcuts (`Cmd+Shift+R` to record, `Cmd+Shift+P` to pause)
44+
- Opus encoding for compact, high-quality audio
45+
46+
**Transcription**
47+
- Real-time on-device transcription powered by [Sherpa ONNX](https://github.com/k2-fsa/sherpa-onnx) (Silero VAD + Parakeet TDT)
48+
- Guided model download on first launch — no manual setup
49+
- Multi-language support
50+
51+
**AI Summarization**
52+
- Local LLM integration via [Ollama](https://ollama.com) — pick any model you like
53+
- Streaming output so you see results as they generate
54+
- Auto-summarize option for hands-free workflow
55+
56+
**Library & Export**
57+
- Searchable meeting library with full-text search
58+
- Card and list views with filters by date, duration, and status
59+
- Export to PDF, ZIP, or Markdown
60+
- Soft delete with trash and recovery
61+
62+
**Customization**
63+
- Light, dark, and system themes
64+
- English and Polish localization
65+
- Configurable audio sources, shortcuts, and data directory
66+
67+
## Quick Start
68+
69+
### Prerequisites
70+
71+
| Dependency | Purpose |
72+
|---|---|
73+
| [Node.js](https://nodejs.org) (LTS) | Frontend tooling |
74+
| [Rust](https://rustup.rs) (stable) | Backend compilation |
75+
| [Bun](https://bun.sh) | Package manager |
76+
| [Ollama](https://ollama.com) | Local LLM for summarization |
77+
78+
### Install & Run
79+
80+
```bash
81+
git clone https://github.com/farce1/opennotes.git
82+
cd opennotes
83+
bun install --frozen-lockfile
84+
bun run tauri dev
85+
```
86+
87+
The app will guide you through downloading transcription models on first launch.
88+
89+
### Build for Production
90+
91+
```bash
92+
bun run tauri build
93+
```
94+
95+
Produces native installers: `.dmg` (macOS), `.msi` / `.exe` (Windows), `.AppImage` / `.deb` (Linux).
96+
97+
## Tech Stack
98+
99+
| Layer | Technology |
100+
|---|---|
101+
| Framework | [Tauri 2](https://tauri.app) |
102+
| Frontend | React 19, TypeScript, Tailwind CSS 4, Vite 7 |
103+
| Backend | Rust, SQLite (via SQLx) |
104+
| Audio | cpal + libopusenc (Opus encoding) |
105+
| Transcription | sherpa-rs (Silero VAD + Parakeet TDT) |
106+
| Summarization | Ollama (local LLM) |
107+
| CI/CD | GitHub Actions — lint, typecheck, build on all platforms |
108+
109+
## Project Structure
110+
111+
```
112+
opennotes/
113+
├── src/ # React frontend
114+
│ ├── components/ # UI components (layout, library, settings, widget)
115+
│ ├── views/ # Page-level views
116+
│ ├── hooks/ # Custom React hooks
117+
│ ├── contexts/ # React context providers
118+
│ ├── lib/ # Utilities (db, export, settings)
119+
│ ├── i18n/ # Translations (en, pl)
120+
│ └── types/ # TypeScript definitions
121+
├── src-tauri/ # Rust backend
122+
│ ├── src/ # Core modules (audio, transcription, session, llm)
123+
│ ├── migrations/ # SQLite schema migrations
124+
│ └── icons/ # App icons (all platforms)
125+
└── .github/workflows/ # CI + release pipelines
126+
```
127+
128+
## Contributing
129+
130+
Contributions are welcome! Whether it's a bug fix, new feature, translation, or documentation improvement — all contributions are appreciated.
131+
132+
1. Fork the repository
133+
2. Create your branch (`git checkout -b feature/my-feature`)
134+
3. Commit your changes
135+
4. Push and open a Pull Request
136+
137+
Please open an issue first for larger changes so we can discuss the approach.
138+
139+
## Roadmap
140+
141+
- [ ] Speaker diarization (who said what)
142+
- [ ] Meeting templates and custom prompts
143+
- [ ] Calendar integration
144+
- [ ] More languages for transcription and UI
145+
- [ ] Plugin system for custom post-processing
146+
147+
Have an idea? [Open an issue](https://github.com/farce1/opennotes/issues) — we'd love to hear it.
148+
149+
## License
150+
151+
[MIT](LICENSE) — use it however you like.
152+
153+
---
154+
155+
<p align="center">
156+
Built with <a href="https://tauri.app">Tauri</a>, <a href="https://react.dev">React</a>, and <a href="https://www.rust-lang.org">Rust</a>.
157+
</p>

0 commit comments

Comments
 (0)