phonograph/README.md

# Phonograph

A friendly, collaborative PostgreSQL derivative for nerds of all stripes.

![Screenshot of multi-cursor editing, as well as a dropdown menu with a highlighted option labeled "PostgreSQL credentials"](./docs/screenshot_multi_cursor.png)

# Development Quickstart

The Phonograph repository comes with a [mise-en-place](https://mise.jdx.dev/)
configuration to automatically manage the development environment:

- `mise install` installs language runtimes and tooling.
- `mise run build-css && mise run build-svelte` builds browser assets.
- `mise run docker-services` runs a Postgres container for local development.
- `mise run server` compiles and runs the server with the dev profile.

## Configuration

Refer to [the .env.example file](./.env.example) for configuration options. An
external OAuth2 provider is required to manage authentication.

# The Phonograph Authorization Model

Refer to documentation in [docs/auth.md](./docs/auth.md).

# Copyright and License

All original source code in this repository is copyright (C) 2025 Second System
Technologies LLC and distributed under the terms in
[the "LICENSE" file](./LICENSE). Certain third-party assets within
[the "static" directory](./static) may be governed by different licenses, for
example the Open Font License or MIT License, as stated by their original
authors. Copies of each relevant license have been included alongside these
files as needed.

# LLM Code Policy

Large language model code generation is permitted sparingly in very limited
cases, for example for completing clearly defined transformations which span
multiple files and are not supported by conventional code actions. All code
generated by LLMs must be thoroughly and frequently reviewed by the author,
before committing affected work.

As of this writing, models display a strong bias towards patterns which are well
represented in public open source projects. This can cause them to tend towards
suboptimal one-size-fits-most or simply outdated coding practices in certain
circumstances. LLM assistance should be sufficiently constrained to avoid
allowing outputs to dictate or implicitly guide significant design decisions.

Furthermore, current language models broadly behave adversarily, in the sense
that they are optimized to make perceiving model outputs versus non-model
outputs as difficult as possible. This can make generated code uniquely
challenging to review effectively. In this context, non-trivial business logic,
particularly logic with security implications, may not be implemented with
direct assistance from LLM tools.

Examples of LLM-assisted changes in practice:

- Replacing SVG icons with similar webfont icons from a different icon pack.
  (Revision `ztrnxzqv` (Git `a8dd49f7`))

# Footnotes

[^1]: Barring historical pedantry, "Postgres" and "PostgreSQL" are essentially
    synonymous and are often used interchangeably. As a matter of convention
    throughout Phonograph docs, "Postgres" is largely used to refer to the
    database software, while "PostgreSQL" is typically used to refer to the
    query language and/or wire protocol.