77 lines
3.6 KiB
Markdown
77 lines
3.6 KiB
Markdown
# Phonograph
|
|
|
|
Phonograph is a friendly, collaborative data platform for nerds of all stripes,
|
|
built around PostgreSQL.
|
|
|
|
Contemporary browser-centric platforms like Airtable open new frontiers for data
|
|
engineering, but they suffer from limitations that conventional databases have
|
|
long since addressed: relational data models are an afterthought; row-level
|
|
security is missing; third party integrations must be implemented piecemeal for
|
|
lack of a standardized API. Phonograph addresses these shortfalls by
|
|
implementing an accessible front-end interface backed by an existing, mature
|
|
database management system.
|
|
|
|
|
|
|
|
## Browser Compatibility Note
|
|
|
|
[CSS anchor positioning](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Anchor_positioning)
|
|
is a relatively new API, and Phonograph uses it extensively. Browser support is
|
|
now fairly good, but
|
|
[Firefox users in particular](https://bugzilla.mozilla.org/show_bug.cgi?id=1988225)
|
|
should upgrade to version 147 or newer for best experience.
|
|
|
|
## 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 is considered reflective of its author, and authors are
|
|
expected to thoroughly and frequently review 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`))
|