# бирка-тян: электронная доска объявлений

_В вашем деле нет пометки об этом!_

бирка-тян (birka-tyan) is a lightweight Danbooru-style imageboard engine for the
purposes of self-hosting a tagged image gallery. It lacks many of the features
one would expect of such an application (particularly use rauthentication), so
if you have a use case other than being able to search through your pictures
when you are not at home, you would be better off looking at an established
solution such as [Danbooru](https://github.com/danbooru/danbooru).

This is a _very_ early release. Perhaps pre-alpha, if there is no stage earlier
in the software release life cycle. Use at your own risk.

If you are brave enough to give this a try, however, feedback of any sort would
be greatly appreciated. The command-line interface and web UI are designed
around my specific use case, but I would ideally like for this to be usable by
the general public.

## Features

- A command-line tool for interacting with the tag database.
- A web interface for querying and viewing files in the tag database.

## Usage

### Command-Line

There are two ways of interacting with бирка-тян: through the `birka-cli`
command-line tool (i), and through the web interface (ii).

The inclusion of (i) is in consideration for this being, essentially, a personal
image gallery. One likely has a loosely-organized collection of images already;
the command-line tool enables her to import images en masse with the full
capabilities of the Unix shell at her fingertips. A brief summary of the
command-line interface follows.

Images are introduced to the database with the `add` command, which takes zero
or more tags following the path of an image. The path is automatically
canonicalized, so relative names are perfectly acceptable.

```sh
$ birka-cli add Cat.jpeg animal cat cute
```

Ah, drat. We should have tagged that image with "photograph", too.

```sh
$ birka-cli add_tags Cat.jpeg photograph
```

On second thought, that wasn't a particularly cute picture.

```sh
$ birka-cli remove_tags Cat.jpeg cute
```

Now, let's see all of the photographs in the tag database tagged with
"photograph".

```sh
$ birka-cli query photograph
/home/jakob/Camera/Cat.jpeg
```

The `query` command outputs a line-separated list of paths to any images
satisfying the query string. The semantics are similar to that of Danbooru,
except that the logical disjunction operator ('~') is unsupported. As a
convenience, the 'query' command can be invoked without a query string, to list
all paths indexed by the database.

```sh
$ birka-cli query
...
```

The tag database is stored in a file, and the path of that file is dependent on
how the program is invoked. If, when parsing the command-line arguments,
`birka-cli` sees a `-o` or `--output` argument, the path following that argument
will be used. Alternatively, the `TB_PATH` environment variable can be
specified, but `-o` takes a higher precedence. If neither are specified,
"birka.db" in the current directory is used.

A few other things that can be done from the command-line:

Removing an image can be done with 'remove'.

```sh
$ birka-cli remove Cat.jpeg
```

Getting the tags in the database:

```sh
$ birka-cli tags
...
```

### Web-Interface (API)

The web interface for бирка-тян exposes a RESTful API for remotely interacting
with the tag database. At the time of writing, this API is __not__ stabilized.
Expect to rewrite any code depending on this API in the near future, in part
because these will all be put behind a `/v1/` specifier.

Suppose we denote the following shape of JSON object as a `ImageResult`.

```
{
  "id": number,
  "filename": string,
  "thumb_filename": string,
  "orig_filename": string,
  "tags": [string, ...],
}
```

The images in the tag database can be enumerated with the 'posts' endpoint,
which takes two parameters: `query`, a query string, and `last`, which is the
last `ImageResult` identifier which was seen. This endpoint will return, at
most, 50 entries, which is why the `last` parameter is necessary.

```
GET /api/posts?last=number,query=string

[zero or more ImageResult]
```

Information about a specific image in the database can be obtained with the
following endpoint, where `id` is the identifier (number) of the image in the
database:

```
GET /api/posts/[id]

ImageResult
```

To add tags to an image, POST a comma-separated list of new tags to the same
endpoint.

To upload an image to the database, post a multipart/form-data encoded message
to the following endpoint with the following fields: `tags`, a comma-separated
list of tags for the files, and `image`, the file to be uploaded.

```
POST /api/posts/[filename]
```

## TODO

There are a few things I'd like to push off 'till later, since this is working
for me right now.

- [birka-cli] Improve the `birka-cli add` interface, allowing multiple files to
  be indexed and tagged in the same invocation.
- [birka-web js] Implement a dynamic "endless scroll" view.
- [birka-web js] Implement a mass-tagger tool in the web interface.