inventory-plus-plus/README.md

## Inventory++ [![Tests Passing?](https://gitea.inventory-plus-plus.com/angel/inventory-plus-plus/actions/workflows/tests.yaml/badge.svg?branch=master)](https://gitea.inventory-plus-plus.com/angel/inventory-plus-plus/actions?workflow=&scoped_workflow_source_repo_id=0&actor=0&status=0&branch=master)

WIP!

This is an application intended to ease the process of managing multiple online stores.
The benefits provided by this application will be to automatically manage shared inventory between stores,
reducing the amount of time needed to synchronize inventory between stores.


## Where things live

Documentation is split up rather than kept in one big doc - start here:

- **[`AGENTS.md`](./AGENTS.md)** - the engineering reference: setup, `make` commands, architecture, database/migration gotchas, testing conventions, auth, and the researched platform-integration priority ranking (which platform to build next, and why).
- **[`ROADMAP.md`](./ROADMAP.md)** - in-progress and planned work, as a checklist.
- **[`research/platforms.md`](./research/platforms.md)** - the underlying API-capability and market-size research the platform-priority ranking is based on.
- **[`domains/platforms/etsy/COMPLIANCE.md`](./domains/platforms/etsy/COMPLIANCE.md)** - Etsy API usage obligations to keep satisfied when touching the Etsy integration.
- **[`diagrams/`](./diagrams)** - architecture and schema diagrams, linked from the Diagrams section below.


## Deploying

The application runs locally, from this directory.
It is deployed simply by running either from the root of the project,
```
make run
```
or
```
go run .
```

See `AGENTS.md` for the full setup/`make` command reference (migrations, tests, dev auth, etc).


## Technology

### Languages

#### Server side
Golang, Go Templates

#### Front end
HTML, CSS, Javascript

### Databases
Postgres, in docker

#### Management
Using [migrate](https://github.com/golang-migrate/migrate) to manage build out the database schema, and to run
migrations.

### Tooling

#### Server side
- github.com/angelbeltran/templater: for wiring up template directories for serving over the web and improving
  the task of composing template together.
- go templates: generating html declaratively from the server.
- github.com/jackc/pgx/v5: for postgres db interfacing

#### Front end
- htmx: for strong hypermedia support
- hyperscript: for minimal, inline scripting, with strong integration with htmx
- tailwind: for styling the front end, using tried and testing styling paradigms, conventions, and templates.


# Architectural and Software Diagrams

## Application structure

See `AGENTS.md`'s Architecture section for the current, maintained breakdown of packages/directories.

![Application structure](./diagrams/application_structure.svg)

## Database schemas

**public**
![Schema](./diagrams/database_schema_public.svg)

**mock**
![Schema](./diagrams/database_schema_mock.svg)


## Events

`domains/raw_events` is the event-sourcing store behind this - see `AGENTS.md`'s Architecture section.

### Event Sourcing Architecture
![Event sourcing architecture](./diagrams/event_sourcing.svg)

### Event Structure
![Event](./diagrams/event.svg)

### Store Event Database Tables
![Event database tables](./diagrams/event_tables.svg)


## Platform: Etsy

### Signing up
![Event database tables](./diagrams/etsy/obtaining_access_token.svg)

### Models
![Models](./diagrams/etsy/models.svg)

See `ROADMAP.md` for what's still unbuilt in the Etsy flow (an account-creation page ahead of OAuth, billing info collection, refresh-token handling), and `domains/platforms/etsy/COMPLIANCE.md` for API usage obligations.


## All Diagrams

All diagrams are stored in the [diagrams](./diagrams) directory