NeonLink

NeonLink is a lightweight, self‑hosted bookmark and link sharing service that prioritizes minimalism without sacrificing functionality. Built with a clear separation of concerns, the application exposes a RESTful API powered by Fastify on the backend and a modern React SPA on the frontend. The choice of technologies keeps the runtime footprint low, enabling deployment on resource‑constrained devices such as Raspberry Pi while still offering a responsive user experience for larger environments.

• Backend: Node.js (≥18) running Fastify, a high‑performance HTTP framework that delivers sub‑millisecond request handling. All business logic—authentication, CRUD operations for bookmarks, tag management, and search—is encapsulated in Fastify plugins. The server is stateless; session data is persisted via JSON Web Tokens (JWT) or basic HTTP auth, allowing horizontal scaling behind a reverse proxy.
• Database: SQLite with the better-sqlite3 driver. SQLite is chosen for its zero‑config, file‑based nature and excellent support in Node.js through a synchronous API that eliminates callbacks. Data is stored under /app/data, making persistence straightforward when mounting host volumes in Docker.
• Frontend: React 18, bundled with Vite for fast rebuilds and tree‑shaking. The UI leverages context and hooks to interact with the backend API, providing features such as auto‑fetching link metadata (icon, title, description) via a lightweight service or external APIs.
• Containerization: Docker images are multi‑arch (ARMv7, AMD64) built with docker buildx. The Dockerfile exposes port 3333, but the container can be mapped to any host port. The image is deliberately slim (node:alpine base) and includes only runtime dependencies, keeping the final image under 200 MB.

• Bookmark CRUD: Endpoints for creating, reading, updating, and deleting links. Each link supports multiple tags, a user‑defined title, custom icon URLs, and optional descriptions.
• Tagging & Search: Full‑text search powered by SQLite’s FTS5 module, enabling rapid query across titles, URLs, and tags.
• Metadata Extraction: On link creation, the server scrapes OpenGraph metadata or falls back to simple HTTP headers. This logic is exposed as a separate endpoint, allowing developers to integrate metadata fetching into their own workflows.
• Webhooks & Extensions: While not fully featured, the architecture allows for custom Fastify plugins to expose additional endpoints or hook into lifecycle events (e.g., onCreate, onDelete). The modular design encourages building lightweight micro‑services that extend NeonLink’s core.

NeonLink is designed for effortless self‑hosting:

• Docker: A single docker run command mounts data and optional background assets. Docker Compose files are provided for quick multi‑container setups (e.g., reverse proxy, SSL termination).
• Scalability: Because the backend is stateless and uses SQLite, scaling horizontally requires a shared filesystem (NFS) or moving to a client‑side database like IndexedDB for truly distributed deployments. For most use cases, a single instance suffices; however, adding a reverse proxy (NGINX, Traefik) and load balancer can distribute traffic across identical containers.
• Resource Footprint: Benchmarks show less than 100 MB RAM usage on a Raspberry Pi 4, making NeonLink ideal for personal cloud setups or intranet services.

Developers can integrate NeonLink into existing ecosystems through:

• REST API: Consume endpoints from any language that can perform HTTP requests.
• Custom Frontends: Replace the bundled React app with a custom SPA or mobile client; the API remains unchanged.
• Plugins: Fastify’s plugin system allows adding authentication layers (OAuth, LDAP), analytics, or custom data models without touching the core codebase.
• Webhooks: Although not yet fully fleshed out, the architecture supports future webhook support for events like “link added” or “tag updated,” enabling real‑time integrations with CI/CD pipelines or notification services.

• Documentation: The README covers installation, development workflow, and build instructions. API routes are inferred from Fastify route handlers; developers can generate OpenAPI specs using plugins if desired.
• Configuration: Environment variables control port, database path, and authentication settings. The Docker entrypoint exposes these as mount points, simplifying CI/CD pipelines.
• Community & Licensing: Licensed under MIT, NeonLink welcomes contributions via GitHub PRs. The project’s small footprint and clear separation of concerns make onboarding fast for new contributors.

1. Personal Bookmark Manager – A single user can host a private, searchable bookmark database on their home server or Raspberry Pi.
2. Team Knowledge Base – Small teams can share links and tags, integrating with existing CI/CD pipelines to automatically post release notes.
3. Embedded Documentation – Projects can embed NeonLink as an internal link hub, exposing a REST API for other services to consume.
4. Learning Platform – Educators can deploy NeonLink on campus servers, allowing students to curate resources with minimal overhead.

NeonLink offers a blend of simplicity and extensibility that appeals to developers who need a self‑hosted