118 lines
3.5 KiB
Markdown
118 lines
3.5 KiB
Markdown
# Electronics Inventory
|
|
|
|
A self-hosted web app for managing an electronics component collection. Track components, their
|
|
field values, physical storage locations, and visual panel/grid layouts.
|
|
|
|
## Features
|
|
|
|
### Components
|
|
Define reusable component types (e.g. Resistor, Capacitor, IC) with custom fields per component.
|
|
Components show up in inventory entries and can be navigated to directly from storage locations.
|
|
|
|
### Fields
|
|
Create custom field definitions (e.g. `resistance`, `capacitance`, `package`) that can be attached
|
|
to any component. Field values are entered per-component instance.
|
|
|
|
### Inventory
|
|
Log where things are stored. Each inventory entry links a component to a storage location.
|
|
Supported location types:
|
|
|
|
- **Grid cell** — a specific row/column in a named grid (e.g. drawer divider box)
|
|
- *(plain entries without a grid reference work too)*
|
|
|
|
### Grids
|
|
Model physical storage grids (drawer organizers, parts boxes, etc.).
|
|
|
|
1. Upload a photo of the grid
|
|
2. Set up corner points to map the image to a logical grid
|
|
3. Define row/column counts
|
|
4. Click any cell to see what's stored there
|
|
|
|
### Templates (Name Formatters)
|
|
Write JavaScript formatter functions that generate smart display names for components based on their
|
|
field values. Example:
|
|
|
|
```js
|
|
(c) => {
|
|
const F = c.fields;
|
|
if (F.resistance && F.imperial_package) {
|
|
return `${F.resistance}Ω ${F.imperial_package}`;
|
|
}
|
|
}
|
|
```
|
|
|
|
Fields are accessed by name (e.g. `c.fields.resistance`). If the formatter returns a non-empty
|
|
string it's used as the display name; otherwise the component's base name is used as fallback.
|
|
Multiple formatters are tried in order.
|
|
|
|
The template editor includes a test data box so you can preview the output without needing real
|
|
inventory data.
|
|
|
|
## Requirements
|
|
|
|
- Node.js >= 25
|
|
- npm
|
|
|
|
## Install
|
|
|
|
Install directly from the git repository — there is no npm package yet:
|
|
|
|
```bash
|
|
npm install git+https://gitea.efforting.tech/mikael-lovqvists-claude-agent/electronics-inventory.git
|
|
```
|
|
|
|
Or clone if you prefer to keep the source around:
|
|
|
|
```bash
|
|
git clone https://gitea.efforting.tech/mikael-lovqvists-claude-agent/electronics-inventory
|
|
cd electronics-inventory
|
|
npm install
|
|
```
|
|
|
|
## Run
|
|
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
The server starts on port 3020, bound to `localhost` only, by default.
|
|
Open [http://localhost:3020](http://localhost:3020) in your browser.
|
|
|
|
Both can be overridden with environment variables:
|
|
|
|
```bash
|
|
PORT=8080 npm start # different port
|
|
BIND_ADDRESS=0.0.0.0 npm start # all interfaces (LAN accessible)
|
|
BIND_ADDRESS=192.168.1.50 npm start # specific interface
|
|
PORT=8080 BIND_ADDRESS=0.0.0.0 npm start # both
|
|
```
|
|
|
|
> **Note:** The default `localhost` binding means the app is only reachable from the same machine.
|
|
> Set `BIND_ADDRESS=0.0.0.0` to expose it on your local network.
|
|
|
|
## Data Storage
|
|
|
|
All data is stored locally in a `data/` directory created automatically on first run:
|
|
|
|
- `data/db.json` — component, field, inventory, grid, and template records (flat key-value store)
|
|
- `data/uploads/` — source images uploaded for grid setup
|
|
|
|
No external database is required.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
server.mjs Express 5 API server + SPA host
|
|
lib/
|
|
storage.mjs Server-side KV store wrappers
|
|
kv-store.mjs JSON file-backed key-value store
|
|
ids.mjs ID generation
|
|
public/
|
|
app.mjs Single-page app (vanilla JS ES modules)
|
|
templates.html HTML templates (lazy-loaded)
|
|
style.css Styles
|
|
lib/api.mjs Fetch wrappers for the REST API
|
|
views/
|
|
grid-setup.mjs Canvas-based grid corner editor
|
|
```
|