GKaszewski/k-notes
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

First batch of smart stuff

Browse Source
This commit is contained in:
Gabriel Kaszewski
2025-12-25 23:53:12 +00:00
parent 4cb398869d
commit 58de25e5bc
34 changed files with 2974 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@@ -4,4 +4,6 @@
*.db-shm
*.db-wal
.DS_Store
*/.DS_Store
*/.DS_Store
/data
/.fastembed_cache

2
ARCHITECTURE.MD
View File

@@ -22,6 +22,7 @@ We are decoupling the **Domain Logic** (the "What") from the **Infrastructure**
| **API Framework** | **Axum** | Actix-Web |
| **Database** | **SQLite (via SQLx)** | PostgreSQL |
| **Search** | **SQLite FTS5** | Meilisearch |
| **Vector Search** | **Qdrant** | Pgvector |
| **Authentication** | **Axum Login** | OIDC (Keycloak/Authelia) |
| **Frontend** | **React + Tailwind + Shadcn/ui** | Vue + Radix |
@@ -79,6 +80,7 @@ Plaintext
- `POST /api/v1/notes` - Create a new note (Accepts Markdown).
- `PATCH /api/v1/notes/:id` - Partial updates.
- `GET /api/v1/search?q=query` - Full-text search via FTS5.
- `GET /api/v1/notes/:id/related` - Get semantically related notes.
## Guidelines & Principles

2130
Cargo.lock generated
View File

File diff suppressed because it is too large Load Diff

12
README.md
View File

@@ -11,6 +11,7 @@ A modern, self-hosted note-taking application built with performance, security,
- **Rich Text**: Markdown support for note content.
- **Version History**: Track changes, view history, note diffs, download versions, and restore previous states.
- **Organization**: Tagging system for easy filtering.
- **Smart Features**: Semantic search and automatically generated related notes using local embeddings.
- **Theme**: Dark and Light mode support.
- **Responsive**: Mobile-friendly UI built with Tailwind CSS.
- **Architecture**:
@@ -25,6 +26,7 @@ A modern, self-hosted note-taking application built with performance, security,
- **Language**: Rust
- **Framework**: Axum
- **Database**: SQLite (Default) or Postgres (Supported via feature flag)
- **Vector Database**: Qdrant (for Smart Features)
- **Dependency Injection**: Manual wiring for clear boundaries
### Frontend
@@ -80,6 +82,16 @@ cargo run -p notes-api --no-default-features --features notes-infra/postgres
```
*Note: Ensure your `DATABASE_URL` is set to a valid Postgres connection string.*
**Feature Flags (Smart Features):**
The application includes "Smart Features" (semantic search, related notes) enabled by default. These require `fastembed`, `qdrant-client`, and `async-nats`.
To build/run **without** smart features (for faster compilation or lighter deployment):
```bash
cargo run -p notes-api --no-default-features --features sqlite
```
#### Frontend
1. Navigate to `k-notes-frontend`.

12
compose.yml
View File

@@ -26,13 +26,23 @@ services:
nats:
image: nats:alpine
container_name: libertas_nats
container_name: k_notes_nats
ports:
- "4222:4222"
- "6222:6222"
- "8222:8222"
restart: unless-stopped
qdrant:
image: qdrant/qdrant:latest
container_name: k_notes_qdrant
ports:
- "6333:6333"
- "6334:6334"
volumes:
- ./data/qdrant_storage:/qdrant/storage:z
restart: unless-stopped
# Optional: Define volumes explicitly if needed
# volumes:
# backend_data:

15
k-notes-frontend/src/components/note-view-dialog.tsx
View File

@@ -8,6 +8,7 @@ import { Edit, Calendar, Pin } from "lucide-react";
import { getNoteColor } from "@/lib/constants";
import clsx from "clsx";
import remarkGfm from "remark-gfm";
import { RelatedNotes } from "./related-notes";
interface NoteViewDialogProps {
@@ -15,9 +16,10 @@ interface NoteViewDialogProps {
open: boolean;
onOpenChange: (open: boolean) => void;
onEdit: () => void;
onSelectNote?: (id: string) => void;
}
export function NoteViewDialog({ note, open, onOpenChange, onEdit }: NoteViewDialogProps) {
export function NoteViewDialog({ note, open, onOpenChange, onEdit, onSelectNote }: NoteViewDialogProps) {
const colorClass = getNoteColor(note.color);
return (
@@ -42,6 +44,17 @@ export function NoteViewDialog({ note, open, onOpenChange, onEdit }: NoteViewDia
<div className="prose dark:prose-invert max-w-none text-base leading-relaxed break-words pb-6">
<ReactMarkdown remarkPlugins={[remarkGfm]}>{note.content}</ReactMarkdown>
</div>
{/* Smart Features: Related Notes */}
<div className="pb-4">
<RelatedNotes
noteId={note.id}
onSelectNote={onSelectNote ? (id) => {
onOpenChange(false);
setTimeout(() => onSelectNote(id), 100); // Small delay to allow dialog close animation?
} : undefined}
/>
</div>
</div>
<DialogFooter className="pt-4 mt-2 border-t border-black/5 dark:border-white/5 flex sm:justify-between items-center gap-4 shrink-0">

62
k-notes-frontend/src/components/related-notes.tsx Normal file
View File

@@ -0,0 +1,62 @@
import { useRelatedNotes } from "@/hooks/use-related-notes";
import { useNotes } from "@/hooks/use-notes";
import { Skeleton } from "@/components/ui/skeleton";
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import { Link2 } from "lucide-react";
interface RelatedNotesProps {
noteId: string;
onSelectNote?: (id: string) => void;
}
export function RelatedNotes({ noteId, onSelectNote }: RelatedNotesProps) {
const { relatedLinks, isRelatedLoading } = useRelatedNotes(noteId);
const { data: notes } = useNotes(); // We need to look up note titles from source_id
if (isRelatedLoading) {
return (
<div className="space-y-2 mt-4">
<h3 className="text-sm font-medium">Related Notes</h3>
<div className="flex flex-wrap gap-2">
<Skeleton className="h-8 w-24" />
<Skeleton className="h-8 w-32" />
</div>
</div>
);
}
if (!relatedLinks || relatedLinks.length === 0) {
return null;
}
return (
<div className="space-y-2 mt-6 border-t pt-4">
<h3 className="text-sm font-medium flex items-center gap-2">
<Link2 className="w-4 h-4" />
Related Notes
</h3>
<div className="flex flex-wrap gap-2">
{relatedLinks.map((link) => {
const targetNote = notes?.find((n: any) => n.id === link.target_note_id);
if (!targetNote) return null;
return (
<Button
key={link.target_note_id}
variant="outline"
size="sm"
className="h-8 text-xs max-w-[200px] justify-start"
onClick={() => onSelectNote?.(link.target_note_id)}
>
<span className="truncate">{targetNote.title || "Untitled"}</span>
<Badge variant="secondary" className="ml-2 text-[10px] h-5 px-1">
{Math.round(link.score * 100)}%
</Badge>
</Button>
);
})}
</div>
</div>
);
}

23
k-notes-frontend/src/hooks/use-related-notes.ts Normal file
View File

@@ -0,0 +1,23 @@
import { useQuery } from "@tanstack/react-query";
import { api } from "@/lib/api";
export interface NoteLink {
source_note_id: string;
target_note_id: string;
score: number;
created_at: string;
}
export function useRelatedNotes(noteId: string | undefined) {
const { data, error, isLoading } = useQuery({
queryKey: ["notes", noteId, "related"],
queryFn: () => api.get(`/notes/${noteId}/related`),
enabled: !!noteId,
});
return {
relatedLinks: data as NoteLink[] | undefined,
isRelatedLoading: isLoading,
relatedError: error,
};
}

14
k-notes-frontend/src/lib/constants.ts
View File

@@ -1,12 +1,12 @@
const NOTE_COLORS = [
{ name: "DEFAULT", value: "bg-background border-border", label: "Default" },
{ name: "RED", value: "bg-red-50 border-red-200 dark:bg-red-950/20 dark:border-red-900", label: "Red" },
{ name: "ORANGE", value: "bg-orange-50 border-orange-200 dark:bg-orange-950/20 dark:border-orange-900", label: "Orange" },
{ name: "YELLOW", value: "bg-yellow-50 border-yellow-200 dark:bg-yellow-950/20 dark:border-yellow-900", label: "Yellow" },
{ name: "GREEN", value: "bg-green-50 border-green-200 dark:bg-green-950/20 dark:border-green-900", label: "Green" },
{ name: "TEAL", value: "bg-teal-50 border-teal-200 dark:bg-teal-950/20 dark:border-teal-900", label: "Teal" },
{ name: "BLUE", value: "bg-blue-50 border-blue-200 dark:bg-blue-950/20 dark:border-blue-900", label: "Blue" },
{ name: "INDIGO", value: "bg-indigo-50 border-indigo-200 dark:bg-indigo-950/20 dark:border-indigo-900", label: "Indigo" },
{ name: "RED", value: "bg-red-50 border-red-200 dark:bg-red-950 dark:border-red-900", label: "Red" },
{ name: "ORANGE", value: "bg-orange-50 border-orange-200 dark:bg-orange-950 dark:border-orange-900", label: "Orange" },
{ name: "YELLOW", value: "bg-yellow-50 border-yellow-200 dark:bg-yellow-950 dark:border-yellow-900", label: "Yellow" },
{ name: "GREEN", value: "bg-green-50 border-green-200 dark:bg-green-950 dark:border-green-900", label: "Green" },
{ name: "TEAL", value: "bg-teal-50 border-teal-200 dark:bg-teal-950 dark:border-teal-900", label: "Teal" },
{ name: "BLUE", value: "bg-blue-50 border-blue-200 dark:bg-blue-950 dark:border-blue-900", label: "Blue" },
{ name: "INDIGO", value: "bg-indigo-50 border-indigo-200 dark:bg-indigo-950 dark:border-indigo-900", label: "Indigo" },
];
export function getNoteColor(colorName: string | undefined): string {

12
migrations/20251226000000_create_note_links.sql Normal file
View File

@@ -0,0 +1,12 @@
CREATE TABLE IF NOT EXISTS note_links (
source_note_id TEXT NOT NULL,
target_note_id TEXT NOT NULL,
score REAL NOT NULL,
created_at DATETIME NOT NULL,
PRIMARY KEY (source_note_id, target_note_id),
FOREIGN KEY (source_note_id) REFERENCES notes(id) ON DELETE CASCADE,
FOREIGN KEY (target_note_id) REFERENCES notes(id) ON DELETE CASCADE
);
CREATE INDEX idx_note_links_source ON note_links(source_note_id);
CREATE INDEX idx_note_links_target ON note_links(target_note_id);

19
notes-api/Cargo.toml
View File

@@ -4,9 +4,25 @@ version = "0.1.0"
edition = "2024"
default-run = "notes-api"
[features]
default = ["sqlite", "smart-features"]
sqlite = [
"notes-infra/sqlite",
"tower-sessions-sqlx-store/sqlite",
"sqlx/sqlite",
]
postgres = [
"notes-infra/postgres",
"tower-sessions-sqlx-store/postgres",
"sqlx/postgres",
]
smart-features = ["notes-infra/smart-features", "dep:async-nats"]
[dependencies]
notes-domain = { path = "../notes-domain" }
notes-infra = { path = "../notes-infra", features = ["sqlite"] }
notes-infra = { path = "../notes-infra", default-features = false, features = [
"sqlite",
] }
# Web framework
axum = { version = "0.8.8", features = ["macros"] }
@@ -20,6 +36,7 @@ tower-sessions-sqlx-store = { version = "0.15", features = ["sqlite"] }
password-auth = "1.0"
time = "0.3"
async-trait = "0.1.89"
async-nats = { version = "0.39", optional = true }
# Async runtime
tokio = { version = "1.48.0", features = ["full"] }

38
notes-api/src/config.rs
View File

@@ -1,3 +1,5 @@
#[cfg(feature = "smart-features")]
use notes_infra::factory::{EmbeddingProvider, VectorProvider};
use std::env;
/// Server configuration
@@ -9,6 +11,11 @@ pub struct Config {
pub session_secret: String,
pub cors_allowed_origins: Vec<String>,
pub allow_registration: bool,
#[cfg(feature = "smart-features")]
pub embedding_provider: EmbeddingProvider,
#[cfg(feature = "smart-features")]
pub vector_provider: VectorProvider,
pub broker_url: String,
}
impl Default for Config {
@@ -21,6 +28,14 @@ impl Default for Config {
.to_string(),
cors_allowed_origins: vec!["http://localhost:5173".to_string()],
allow_registration: true,
#[cfg(feature = "smart-features")]
embedding_provider: EmbeddingProvider::FastEmbed,
#[cfg(feature = "smart-features")]
vector_provider: VectorProvider::Qdrant {
url: "http://localhost:6334".to_string(),
collection: "notes".to_string(),
},
broker_url: "nats://localhost:4222".to_string(),
}
}
}
@@ -56,6 +71,24 @@ impl Config {
.map(|s| s.to_lowercase() == "true")
.unwrap_or(true);
#[cfg(feature = "smart-features")]
let embedding_provider = match env::var("EMBEDDING_PROVIDER").unwrap_or_default().as_str() {
// Future: "ollama" => EmbeddingProvider::Ollama(...),
_ => EmbeddingProvider::FastEmbed,
};
#[cfg(feature = "smart-features")]
let vector_provider = match env::var("VECTOR_PROVIDER").unwrap_or_default().as_str() {
// Future: "postgres" => ...
_ => VectorProvider::Qdrant {
url: env::var("QDRANT_URL").unwrap_or_else(|_| "http://localhost:6334".to_string()),
collection: env::var("QDRANT_COLLECTION").unwrap_or_else(|_| "notes".to_string()),
},
};
let broker_url =
env::var("BROKER_URL").unwrap_or_else(|_| "nats://localhost:4222".to_string());
Self {
host,
port,
@@ -63,6 +96,11 @@ impl Config {
session_secret,
cors_allowed_origins,
allow_registration,
#[cfg(feature = "smart-features")]
embedding_provider,
#[cfg(feature = "smart-features")]
vector_provider,
broker_url,
}
}
}

20
notes-api/src/dto.rs
View File

@@ -172,3 +172,23 @@ impl From<notes_domain::NoteVersion> for NoteVersionResponse {
pub struct ConfigResponse {
pub allow_registration: bool,
}
/// Note Link response DTO
#[derive(Debug, Serialize)]
pub struct NoteLinkResponse {
pub source_note_id: Uuid,
pub target_note_id: Uuid,
pub score: f32,
pub created_at: DateTime<Utc>,
}
impl From<notes_domain::entities::NoteLink> for NoteLinkResponse {
fn from(link: notes_domain::entities::NoteLink) -> Self {
Self {
source_note_id: link.source_note_id,
target_note_id: link.target_note_id,
score: link.score,
created_at: link.created_at,
}
}
}

4
notes-api/src/error.rs
View File

@@ -55,7 +55,9 @@ impl IntoResponse for ApiError {
DomainError::Unauthorized(_) => StatusCode::FORBIDDEN,
DomainError::RepositoryError(_) => StatusCode::INTERNAL_SERVER_ERROR,
DomainError::RepositoryError(_) | DomainError::InfrastructureError(_) => {
StatusCode::INTERNAL_SERVER_ERROR
}
};
(

26
notes-api/src/main.rs
View File

@@ -43,6 +43,8 @@ async fn main() -> anyhow::Result<()> {
tracing::info!("Connecting to database: {}", config.database_url);
let db_config = DatabaseConfig::new(&config.database_url);
#[cfg(feature = "smart-features")]
use notes_infra::factory::build_link_repository;
use notes_infra::factory::{
build_database_pool, build_note_repository, build_session_store, build_tag_repository,
build_user_repository,
@@ -52,7 +54,6 @@ async fn main() -> anyhow::Result<()> {
.map_err(|e| anyhow::anyhow!(e))?;
// Run migrations
// The factory/infra layer abstracts the database type
if let Err(e) = run_migrations(&pool).await {
tracing::warn!(
"Migration error (might be expected if not implemented for this DB): {}",
@@ -73,6 +74,10 @@ async fn main() -> anyhow::Result<()> {
let user_repo = build_user_repository(&pool)
.await
.map_err(|e| anyhow::anyhow!(e))?;
#[cfg(feature = "smart-features")]
let link_repo = build_link_repository(&pool)
.await
.map_err(|e| anyhow::anyhow!(e))?;
// Create services
use notes_domain::{NoteService, TagService, UserService};
@@ -80,14 +85,28 @@ async fn main() -> anyhow::Result<()> {
let tag_service = Arc::new(TagService::new(tag_repo.clone()));
let user_service = Arc::new(UserService::new(user_repo.clone()));
// Connect to NATS
// Connect to NATS
#[cfg(feature = "smart-features")]
let nats_client = {
tracing::info!("Connecting to NATS: {}", config.broker_url);
async_nats::connect(&config.broker_url)
.await
.map_err(|e| anyhow::anyhow!("NATS connection failed: {}", e))?
};
// Create application state
let state = AppState::new(
note_repo,
tag_repo,
user_repo.clone(),
#[cfg(feature = "smart-features")]
link_repo,
note_service,
tag_service,
user_service,
#[cfg(feature = "smart-features")]
nats_client,
config.clone(),
);
@@ -108,10 +127,8 @@ async fn main() -> anyhow::Result<()> {
.with_secure(false) // Set to true in production with HTTPS
.with_expiry(Expiry::OnInactivity(Duration::seconds(60 * 60 * 24 * 7))); // 7 days
// Auth layer
let auth_layer = AuthManagerLayerBuilder::new(backend, session_layer).build();
// Parse CORS origins
let mut cors = CorsLayer::new()
.allow_methods([
axum::http::Method::GET,
@@ -127,7 +144,6 @@ async fn main() -> anyhow::Result<()> {
])
.allow_credentials(true);
// Add allowed origins
let mut allowed_origins = Vec::new();
for origin in &config.cors_allowed_origins {
tracing::debug!("Allowing CORS origin: {}", origin);
@@ -142,7 +158,6 @@ async fn main() -> anyhow::Result<()> {
cors = cors.allow_origin(allowed_origins);
}
// Build the application
let app = Router::new()
.nest("/api/v1", routes::api_v1_router())
.layer(auth_layer)
@@ -150,7 +165,6 @@ async fn main() -> anyhow::Result<()> {
.layer(TraceLayer::new_for_http())
.with_state(state);
// Start the server
let addr = format!("{}:{}", config.host, config.port);
let listener = tokio::net::TcpListener::bind(&addr).await?;

9
notes-api/src/routes/mod.rs
View File

@@ -15,7 +15,7 @@ use crate::state::AppState;
/// Create the API v1 router
pub fn api_v1_router() -> Router<AppState> {
Router::new()
let router = Router::new()
// Auth routes
.route("/auth/register", post(auth::register))
.route("/auth/login", post(auth::login))
@@ -29,7 +29,12 @@ pub fn api_v1_router() -> Router<AppState> {
.patch(notes::update_note)
.delete(notes::delete_note),
)
.route("/notes/{id}/versions", get(notes::list_note_versions))
.route("/notes/{id}/versions", get(notes::list_note_versions));
#[cfg(feature = "smart-features")]
let router = router.route("/notes/{id}/related", get(notes::get_related_notes));
router
// Search route
.route("/search", get(notes::search_notes))
// Import/Export routes

62
notes-api/src/routes/notes.rs
View File

@@ -82,6 +82,21 @@ pub async fn create_note(
let note = state.note_service.create_note(domain_req).await?;
// Publish event
#[cfg(feature = "smart-features")]
{
let payload = serde_json::to_vec(&note).unwrap_or_default();
if let Err(e) = state
.nats_client
.publish("notes.updated", payload.into())
.await
{
tracing::error!("Failed to publish notes.updated event: {}", e);
} else {
tracing::info!("Published notes.updated event for note {}", note.id);
}
}
Ok((StatusCode::CREATED, Json(NoteResponse::from(note))))
}
@@ -137,6 +152,21 @@ pub async fn update_note(
let note = state.note_service.update_note(domain_req).await?;
// Publish event
#[cfg(feature = "smart-features")]
{
let payload = serde_json::to_vec(&note).unwrap_or_default();
if let Err(e) = state
.nats_client
.publish("notes.updated", payload.into())
.await
{
tracing::error!("Failed to publish notes.updated event: {}", e);
} else {
tracing::info!("Published notes.updated event for note {}", note.id);
}
}
Ok(Json(NoteResponse::from(note)))
}
@@ -160,7 +190,7 @@ pub async fn delete_note(
}
/// Search notes
/// GET /api/v1/search
/// GET /api/v1/notes/search
pub async fn search_notes(
State(state): State<AppState>,
auth: AuthSession<AuthBackend>,
@@ -201,3 +231,33 @@ pub async fn list_note_versions(
Ok(Json(response))
}
/// Get related notes
/// GET /api/v1/notes/:id/related
/// Get related notes
/// GET /api/v1/notes/:id/related
#[cfg(feature = "smart-features")]
pub async fn get_related_notes(
State(state): State<AppState>,
auth: AuthSession<AuthBackend>,
Path(id): Path<Uuid>,
) -> ApiResult<Json<Vec<crate::dto::NoteLinkResponse>>> {
let user = auth
.user
.ok_or(ApiError::Domain(notes_domain::DomainError::Unauthorized(
"Login required".to_string(),
)))?;
let user_id = user.id();
// Verify access to the source note
state.note_service.get_note(id, user_id).await?;
// Get links
let links = state.link_repo.get_links_for_note(id).await?;
let response: Vec<crate::dto::NoteLinkResponse> = links
.into_iter()
.map(crate::dto::NoteLinkResponse::from)
.collect();
Ok(Json(response))
}

10
notes-api/src/state.rs
View File

@@ -11,9 +11,13 @@ pub struct AppState {
pub note_repo: Arc<dyn NoteRepository>,
pub tag_repo: Arc<dyn TagRepository>,
pub user_repo: Arc<dyn UserRepository>,
#[cfg(feature = "smart-features")]
pub link_repo: Arc<dyn notes_domain::ports::LinkRepository>,
pub note_service: Arc<NoteService>,
pub tag_service: Arc<TagService>,
pub user_service: Arc<UserService>,
#[cfg(feature = "smart-features")]
pub nats_client: async_nats::Client,
pub config: Config,
}
@@ -22,18 +26,24 @@ impl AppState {
note_repo: Arc<dyn NoteRepository>,
tag_repo: Arc<dyn TagRepository>,
user_repo: Arc<dyn UserRepository>,
#[cfg(feature = "smart-features")] link_repo: Arc<dyn notes_domain::ports::LinkRepository>,
note_service: Arc<NoteService>,
tag_service: Arc<TagService>,
user_service: Arc<UserService>,
#[cfg(feature = "smart-features")] nats_client: async_nats::Client,
config: Config,
) -> Self {
Self {
note_repo,
tag_repo,
user_repo,
#[cfg(feature = "smart-features")]
link_repo,
note_service,
tag_service,
user_service,
#[cfg(feature = "smart-features")]
nats_client,
config,
}
}

21
notes-domain/src/entities.rs
View File

@@ -204,6 +204,27 @@ impl NoteVersion {
}
}
/// A derived link between two notes, typically generated by semantic similarity.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct NoteLink {
pub source_note_id: Uuid,
pub target_note_id: Uuid,
/// Similarity score (0.0 to 1.0)
pub score: f32,
pub created_at: DateTime<Utc>,
}
impl NoteLink {
pub fn new(source_note_id: Uuid, target_note_id: Uuid, score: f32) -> Self {
Self {
source_note_id,
target_note_id,
score,
created_at: Utc::now(),
}
}
}
/// Filter options for querying notes
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct NoteFilter {

4
notes-domain/src/errors.rs
View File

@@ -47,6 +47,10 @@ pub enum DomainError {
/// A repository/infrastructure error occurred
#[error("Repository error: {0}")]
RepositoryError(String),
/// An infrastructure adapter error occurred
#[error("Infrastructure error: {0}")]
InfrastructureError(String),
}
impl DomainError {

1
notes-domain/src/lib.rs
View File

@@ -10,6 +10,7 @@
pub mod entities;
pub mod errors;
pub mod ports;
pub mod repositories;
pub mod services;

36
notes-domain/src/ports.rs Normal file
View File

@@ -0,0 +1,36 @@
use async_trait::async_trait;
use uuid::Uuid;
use crate::entities::NoteLink;
use crate::errors::DomainResult;
/// Defines how to generate vector embeddings from text.
#[async_trait]
pub trait EmbeddingGenerator: Send + Sync {
/// Generate a vector embedding for the given text.
async fn generate_embedding(&self, text: &str) -> DomainResult<Vec<f32>>;
}
/// Defines how to store and retrieve vectors.
#[async_trait]
pub trait VectorStore: Send + Sync {
/// Upsert a vector for a given note ID.
async fn upsert(&self, id: Uuid, vector: &[f32]) -> DomainResult<()>;
/// Find similar items to the given vector.
/// Returns a list of (NoteID, Score) tuples.
async fn find_similar(&self, vector: &[f32], limit: usize) -> DomainResult<Vec<(Uuid, f32)>>;
}
/// Defines how to persist note links.
#[async_trait]
pub trait LinkRepository: Send + Sync {
/// Save a batch of generated links.
async fn save_links(&self, links: &[NoteLink]) -> DomainResult<()>;
/// Delete existing links for a specific source note (e.g., before regenerating).
async fn delete_links_for_source(&self, source_note_id: Uuid) -> DomainResult<()>;
/// Get links for a specific source note.
async fn get_links_for_note(&self, source_note_id: Uuid) -> DomainResult<Vec<NoteLink>>;
}

60
notes-domain/src/services.rs
View File

@@ -356,6 +356,66 @@ impl UserService {
}
}
/// Service for Smart Features (Embeddings, Vector Search, Linking)
pub struct SmartNoteService {
embedding_generator: Arc<dyn crate::ports::EmbeddingGenerator>,
vector_store: Arc<dyn crate::ports::VectorStore>,
link_repo: Arc<dyn crate::ports::LinkRepository>,
}
impl SmartNoteService {
pub fn new(
embedding_generator: Arc<dyn crate::ports::EmbeddingGenerator>,
vector_store: Arc<dyn crate::ports::VectorStore>,
link_repo: Arc<dyn crate::ports::LinkRepository>,
) -> Self {
Self {
embedding_generator,
vector_store,
link_repo,
}
}
/// Process a note to generate embeddings and find similar notes
pub async fn process_note(&self, note: &Note) -> DomainResult<()> {
// 1. Generate embedding
let embedding = self
.embedding_generator
.generate_embedding(&note.content)
.await?;
// 2. Upsert to vector store
self.vector_store.upsert(note.id, &embedding).await?;
// 3. Find similar notes
// TODO: Make limit configurable
let similar = self.vector_store.find_similar(&embedding, 5).await?;
// 4. Create links
let links: Vec<crate::entities::NoteLink> = similar
.into_iter()
.filter(|(id, _)| *id != note.id) // Exclude self
.map(|(target_id, score)| crate::entities::NoteLink::new(note.id, target_id, score))
.collect();
// 5. Save links (replacing old ones)
if !links.is_empty() {
self.link_repo.delete_links_for_source(note.id).await?;
self.link_repo.save_links(&links).await?;
}
Ok(())
}
/// Get related notes for a given note ID
pub async fn get_related_notes(
&self,
note_id: Uuid,
) -> DomainResult<Vec<crate::entities::NoteLink>> {
self.link_repo.get_links_for_note(note_id).await
}
}
#[cfg(test)]
mod tests {
use super::*;

6
notes-infra/Cargo.toml
View File

@@ -4,9 +4,10 @@ version = "0.1.0"
edition = "2024"
[features]
default = ["sqlite"]
default = ["sqlite", "smart-features"]
sqlite = ["sqlx/sqlite", "tower-sessions-sqlx-store/sqlite"]
postgres = ["sqlx/postgres", "tower-sessions-sqlx-store/postgres"]
smart-features = ["dep:fastembed", "dep:qdrant-client"]
[dependencies]
notes-domain = { path = "../notes-domain" }
@@ -19,3 +20,6 @@ tracing = "0.1"
uuid = { version = "1.19.0", features = ["v4", "serde"] }
tower-sessions = "0.14.0"
tower-sessions-sqlx-store = { version = "0.15.0", default-features = false }
fastembed = { version = "5.4", optional = true }
qdrant-client = { version = "1.16", optional = true }
serde_json = "1.0"

48
notes-infra/src/embeddings/fastembed.rs Normal file
View File

@@ -0,0 +1,48 @@
use async_trait::async_trait;
use fastembed::{EmbeddingModel, InitOptions, TextEmbedding};
use notes_domain::errors::{DomainError, DomainResult};
use notes_domain::ports::EmbeddingGenerator;
use std::sync::{Arc, Mutex};
pub struct FastEmbedAdapter {
model: Arc<Mutex<TextEmbedding>>,
}
impl FastEmbedAdapter {
pub fn new() -> DomainResult<Self> {
let mut options = InitOptions::default();
options.model_name = EmbeddingModel::AllMiniLML6V2;
options.show_download_progress = false;
let model = TextEmbedding::try_new(options).map_err(|e| {
DomainError::InfrastructureError(format!("Failed to init fastembed: {}", e))
})?;
Ok(Self {
model: Arc::new(Mutex::new(model)),
})
}
}
#[async_trait]
impl EmbeddingGenerator for FastEmbedAdapter {
async fn generate_embedding(&self, text: &str) -> DomainResult<Vec<f32>> {
let model = self.model.clone();
let text = text.to_string();
let embeddings = tokio::task::spawn_blocking(move || {
let mut model = model.lock().map_err(|e| format!("Lock error: {}", e))?;
model
.embed(vec![text], None)
.map_err(|e| format!("Embed error: {}", e))
})
.await
.map_err(|e| DomainError::InfrastructureError(format!("Join error: {}", e)))?
.map_err(|e| DomainError::InfrastructureError(e))?;
embeddings
.into_iter()
.next()
.ok_or_else(|| DomainError::InfrastructureError("No embedding generated".to_string()))
}
}

1
notes-infra/src/embeddings/mod.rs Normal file
View File

@@ -0,0 +1 @@
pub mod fastembed;

56
notes-infra/src/factory.rs
View File

@@ -11,10 +11,66 @@ pub enum FactoryError {
Database(#[from] sqlx::Error),
#[error("Not implemented: {0}")]
NotImplemented(String),
#[error("Infrastructure error: {0}")]
Infrastructure(#[from] notes_domain::DomainError),
}
pub type FactoryResult<T> = Result<T, FactoryError>;
#[cfg(feature = "smart-features")]
#[derive(Debug, Clone)]
pub enum EmbeddingProvider {
FastEmbed,
// Ollama(String), // Url
// OpenAI(String), // ApiKey
}
#[cfg(feature = "smart-features")]
#[derive(Debug, Clone)]
pub enum VectorProvider {
Qdrant { url: String, collection: String },
// InMemory,
}
#[cfg(feature = "smart-features")]
pub async fn build_embedding_generator(
provider: &EmbeddingProvider,
) -> FactoryResult<Arc<dyn notes_domain::ports::EmbeddingGenerator>> {
match provider {
EmbeddingProvider::FastEmbed => {
let adapter = crate::embeddings::fastembed::FastEmbedAdapter::new()?;
Ok(Arc::new(adapter))
}
}
}
#[cfg(feature = "smart-features")]
pub async fn build_vector_store(
provider: &VectorProvider,
) -> FactoryResult<Arc<dyn notes_domain::ports::VectorStore>> {
match provider {
VectorProvider::Qdrant { url, collection } => {
let adapter = crate::vector::qdrant::QdrantVectorAdapter::new(url, collection)?;
adapter.create_collection_if_not_exists().await?;
Ok(Arc::new(adapter))
}
}
}
#[cfg(feature = "sqlite")]
pub async fn build_link_repository(
pool: &DatabasePool,
) -> FactoryResult<Arc<dyn notes_domain::ports::LinkRepository>> {
match pool {
DatabasePool::Sqlite(pool) => Ok(Arc::new(
crate::link_repository::SqliteLinkRepository::new(pool.clone()),
)),
_ => Err(FactoryError::NotImplemented(
"LinkRepostiory for non-sqlite".to_string(),
)),
}
}
pub async fn build_database_pool(db_config: &DatabaseConfig) -> FactoryResult<DatabasePool> {
if db_config.url.starts_with("sqlite:") {
#[cfg(feature = "sqlite")]

8
notes-infra/src/lib.rs
View File

@@ -15,20 +15,28 @@
//! - [`db::run_migrations`] - Run database migrations
pub mod db;
#[cfg(feature = "smart-features")]
pub mod embeddings;
pub mod factory;
#[cfg(feature = "sqlite")]
pub mod link_repository;
#[cfg(feature = "sqlite")]
pub mod note_repository;
pub mod session_store;
#[cfg(feature = "sqlite")]
pub mod tag_repository;
#[cfg(feature = "sqlite")]
pub mod user_repository;
#[cfg(feature = "smart-features")]
pub mod vector;
// Re-export for convenience
#[cfg(feature = "sqlite")]
pub use db::create_pool;
pub use db::{DatabaseConfig, run_migrations};
#[cfg(feature = "sqlite")]
pub use link_repository::SqliteLinkRepository;
#[cfg(feature = "sqlite")]
pub use note_repository::SqliteNoteRepository;
#[cfg(feature = "sqlite")]
pub use tag_repository::SqliteTagRepository;

111
notes-infra/src/link_repository.rs Normal file
View File

@@ -0,0 +1,111 @@
use async_trait::async_trait;
use sqlx::SqlitePool;
use uuid::Uuid;
use notes_domain::entities::NoteLink;
use notes_domain::errors::{DomainError, DomainResult};
use notes_domain::ports::LinkRepository;
pub struct SqliteLinkRepository {
pool: SqlitePool,
}
impl SqliteLinkRepository {
pub fn new(pool: SqlitePool) -> Self {
Self { pool }
}
}
#[async_trait]
impl LinkRepository for SqliteLinkRepository {
async fn save_links(&self, links: &[NoteLink]) -> DomainResult<()> {
let mut tx = self
.pool
.begin()
.await
.map_err(|e| DomainError::RepositoryError(e.to_string()))?;
for link in links {
let source = link.source_note_id.to_string();
let target = link.target_note_id.to_string();
let created_at = link.created_at.to_rfc3339();
sqlx::query(
r#"
INSERT INTO note_links (source_note_id, target_note_id, score, created_at)
VALUES (?, ?, ?, ?)
ON CONFLICT(source_note_id, target_note_id) DO UPDATE SET
score = excluded.score,
created_at = excluded.created_at
"#,
)
.bind(source)
.bind(target)
.bind(link.score)
.bind(created_at)
.execute(&mut *tx)
.await
.map_err(|e| DomainError::RepositoryError(e.to_string()))?;
}
tx.commit()
.await
.map_err(|e| DomainError::RepositoryError(e.to_string()))?;
Ok(())
}
async fn delete_links_for_source(&self, source_note_id: Uuid) -> DomainResult<()> {
let source_str = source_note_id.to_string();
sqlx::query("DELETE FROM note_links WHERE source_note_id = ?")
.bind(source_str)
.execute(&self.pool)
.await
.map_err(|e| DomainError::RepositoryError(e.to_string()))?;
Ok(())
}
async fn get_links_for_note(&self, source_note_id: Uuid) -> DomainResult<Vec<NoteLink>> {
let source_str = source_note_id.to_string();
// We select links where the note is the source
// TODO: Should we also include links where the note is the target?
// For now, let's stick to outgoing links as defined by the service logic.
// Actually, semantic similarity is symmetric, but we only save (A -> B) if we process A.
// Ideally we should look for both directions or enforce symmetry.
// Given current implementation saves A->B when A is processed, if B is processed it saves B->A.
// So just querying source_note_id is fine if we assume all notes are processed.
let links = sqlx::query_as::<_, SqliteNoteLink>(
"SELECT * FROM note_links WHERE source_note_id = ? ORDER BY score DESC",
)
.bind(source_str)
.fetch_all(&self.pool)
.await
.map_err(|e| DomainError::RepositoryError(e.to_string()))?;
Ok(links.into_iter().map(NoteLink::from).collect())
}
}
#[derive(sqlx::FromRow)]
struct SqliteNoteLink {
source_note_id: String,
target_note_id: String,
score: f32,
created_at: String, // Stored as ISO string
}
impl From<SqliteNoteLink> for NoteLink {
fn from(row: SqliteNoteLink) -> Self {
Self {
source_note_id: Uuid::parse_str(&row.source_note_id).unwrap_or_default(),
target_note_id: Uuid::parse_str(&row.target_note_id).unwrap_or_default(),
score: row.score,
created_at: chrono::DateTime::parse_from_rfc3339(&row.created_at)
.unwrap_or_default()
.with_timezone(&chrono::Utc),
}
}
}

1
notes-infra/src/vector/mod.rs Normal file
View File

@@ -0,0 +1 @@
pub mod qdrant;

101
notes-infra/src/vector/qdrant.rs Normal file
View File

@@ -0,0 +1,101 @@
use async_trait::async_trait;
use notes_domain::errors::{DomainError, DomainResult};
use notes_domain::ports::VectorStore;
use qdrant_client::Qdrant;
use qdrant_client::qdrant::{
CreateCollectionBuilder, Distance, PointStruct, SearchPointsBuilder, UpsertPointsBuilder,
Value, VectorParamsBuilder,
};
use std::collections::HashMap;
use std::sync::Arc;
use uuid::Uuid;
pub struct QdrantVectorAdapter {
client: Arc<Qdrant>,
collection_name: String,
}
impl QdrantVectorAdapter {
pub fn new(url: &str, collection_name: &str) -> DomainResult<Self> {
let client = Qdrant::from_url(url).build().map_err(|e| {
DomainError::InfrastructureError(format!("Failed to create Qdrant client: {}", e))
})?;
Ok(Self {
client: Arc::new(client),
collection_name: collection_name.to_string(),
})
}
pub async fn create_collection_if_not_exists(&self) -> DomainResult<()> {
if !self
.client
.collection_exists(&self.collection_name)
.await
.map_err(|e| {
DomainError::InfrastructureError(format!(
"Failed to check collection existence: {}",
e
))
})?
{
self.client
.create_collection(
CreateCollectionBuilder::new(self.collection_name.clone())
.vectors_config(VectorParamsBuilder::new(384, Distance::Cosine)),
)
.await
.map_err(|e| {
DomainError::InfrastructureError(format!("Failed to create collection: {}", e))
})?;
}
Ok(())
}
}
#[async_trait]
impl VectorStore for QdrantVectorAdapter {
async fn upsert(&self, id: Uuid, vector: &[f32]) -> DomainResult<()> {
let payload: HashMap<String, Value> = HashMap::new();
let point = PointStruct::new(id.to_string(), vector.to_vec(), payload);
let upsert_points = UpsertPointsBuilder::new(self.collection_name.clone(), vec![point]);
self.client
.upsert_points(upsert_points)
.await
.map_err(|e| DomainError::InfrastructureError(format!("Qdrant upsert error: {}", e)))?;
Ok(())
}
async fn find_similar(&self, vector: &[f32], limit: usize) -> DomainResult<Vec<(Uuid, f32)>> {
let search_points =
SearchPointsBuilder::new(self.collection_name.clone(), vector.to_vec(), limit as u64)
.with_payload(true);
let search_result = self
.client
.search_points(search_points)
.await
.map_err(|e| DomainError::InfrastructureError(format!("Qdrant search error: {}", e)))?;
let results = search_result
.result
.into_iter()
.filter_map(|point| {
let id = point.id?;
let uuid_str = match id.point_id_options? {
qdrant_client::qdrant::point_id::PointIdOptions::Uuid(u) => u,
_ => return None,
};
let uuid = Uuid::parse_str(&uuid_str).ok()?;
Some((uuid, point.score))
})
.collect();
Ok(results)
}
}

8
notes-worker/Cargo.toml
View File

@@ -3,11 +3,17 @@ name = "notes-worker"
version = "0.1.0"
edition = "2024"
[features]
default = ["sqlite", "smart-features"]
sqlite = ["notes-infra/sqlite", "sqlx/sqlite"]
# postgres = ["notes-infra/postgres", "sqlx/postgres"]
smart-features = ["notes-infra/smart-features"]
[dependencies]
anyhow = "1.0.100"
async-nats = "0.45.0"
notes-domain = { path = "../notes-domain" }
notes-infra = { path = "../notes-infra" }
notes-infra = { path = "../notes-infra", default-features = false }
serde = { version = "1.0.228", features = ["derive"] }
serde_json = "1.0.146"
tokio = { version = "1.48.0", features = ["full"] }

39
notes-worker/src/config.rs
View File

@@ -1,7 +1,14 @@
#[cfg(feature = "smart-features")]
use notes_infra::factory::{EmbeddingProvider, VectorProvider};
#[derive(Debug, Clone)]
pub struct Config {
pub broker_url: String,
pub database_url: String,
#[cfg(feature = "smart-features")]
pub embedding_provider: EmbeddingProvider,
#[cfg(feature = "smart-features")]
pub vector_provider: VectorProvider,
}
impl Default for Config {
@@ -9,6 +16,13 @@ impl Default for Config {
Self {
broker_url: "nats://localhost:4222".to_string(),
database_url: "sqlite::memory:".to_string(),
#[cfg(feature = "smart-features")]
embedding_provider: EmbeddingProvider::FastEmbed,
#[cfg(feature = "smart-features")]
vector_provider: VectorProvider::Qdrant {
url: "http://localhost:6334".to_string(),
collection: "notes".to_string(),
},
}
}
}
@@ -17,9 +31,34 @@ impl Config {
pub fn from_env() -> Self {
let _ = dotenvy::dotenv();
#[cfg(feature = "smart-features")]
let embedding_provider = match std::env::var("EMBEDDING_PROVIDER")
.unwrap_or_default()
.as_str()
{
_ => EmbeddingProvider::FastEmbed,
};
#[cfg(feature = "smart-features")]
let vector_provider = match std::env::var("VECTOR_PROVIDER")
.unwrap_or_default()
.as_str()
{
_ => VectorProvider::Qdrant {
url: std::env::var("QDRANT_URL")
.unwrap_or_else(|_| "http://localhost:6334".to_string()),
collection: std::env::var("QDRANT_COLLECTION")
.unwrap_or_else(|_| "notes".to_string()),
},
};
Self {
broker_url: std::env::var("BROKER_URL").unwrap_or("nats://localhost:4222".to_string()),
database_url: std::env::var("DATABASE_URL").unwrap_or("sqlite::memory:".to_string()),
#[cfg(feature = "smart-features")]
embedding_provider,
#[cfg(feature = "smart-features")]
vector_provider,
}
}
}

73
notes-worker/src/main.rs
View File

@@ -1,16 +1,77 @@
use notes_infra::{DatabaseConfig, create_pool};
use futures_util::StreamExt;
#[cfg(feature = "smart-features")]
use notes_domain::services::SmartNoteService;
#[cfg(feature = "smart-features")]
use notes_infra::{
DatabaseConfig,
factory::{
build_database_pool, build_embedding_generator, build_link_repository, build_vector_store,
},
};
use crate::config::Config;
mod config;
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let config = Config::from_env();
let nats_client = async_nats::connect(config.broker_url).await?;
let db_config = DatabaseConfig::new(config.database_url);
let db_pool = create_pool(&db_config).await?;
tracing_subscriber::registry()
.with(
tracing_subscriber::EnvFilter::try_from_default_env()
.unwrap_or_else(|_| "notes_worker=info,notes_infra=info".into()),
)
.with(tracing_subscriber::fmt::layer())
.init();
let config = Config::from_env();
let nats_client = async_nats::connect(&config.broker_url).await?;
#[cfg(feature = "smart-features")]
{
let db_config = DatabaseConfig::new(config.database_url.clone());
let db_pool = build_database_pool(&db_config).await?;
// Initialize smart feature adapters
let embedding_generator = build_embedding_generator(&config.embedding_provider).await?;
let vector_store = build_vector_store(&config.vector_provider).await?;
let link_repo = build_link_repository(&db_pool).await?;
// Create the service
let smart_service = SmartNoteService::new(embedding_generator, vector_store, link_repo);
tracing::info!(
"SmartNoteService initialized successfully with {:?}",
config.embedding_provider
);
// Subscribe to note update events
let mut subscriber = nats_client.subscribe("notes.updated").await?;
tracing::info!("Worker listening on 'notes.updated'...");
while let Some(msg) = subscriber.next().await {
// Parse message payload (assuming the payload IS the Note JSON)
let note_result: Result<notes_domain::Note, _> = serde_json::from_slice(&msg.payload);
match note_result {
Ok(note) => {
tracing::info!("Processing smart features for note: {}", note.id);
match smart_service.process_note(&note).await {
Ok(_) => tracing::info!("Successfully processed note {}", note.id),
Err(e) => tracing::error!("Failed to process note {}: {}", note.id, e),
}
}
Err(e) => {
tracing::error!("Failed to deserialize note from message: {}", e);
}
}
}
}
#[cfg(not(feature = "smart-features"))]
{
tracing::info!("Smart features are disabled. Worker will exit.");
}
// subscribe to jobs and process them
Ok(())
}