Repository Layout

Use this map as a quick orientation when extending Postgram.

What this page covers

Key directories and their responsibilities.

Reference

src/
  auth/            API key and auth middleware
  cli/             user/admin CLI logic
  db/              Pool and migration helpers
  migrate-talon/   Talon import tooling
  services/        Business domain services
  transport/       REST and MCP adapters
  types/           Shared type definitions
  util/            Errors, audit, and logging

cli/               Published `@ivotoby/postgram-cli` package
ui/                User-facing Web UI and Admin UI
docker/            Container entrypoint and secret bootstrap scripts
bin/               Local operator wrappers

packages/
  browser-extension-chrome/   Chromium web clipper
  browser-extension-firefox/  Firefox web clipper

tests/
  contract/        REST/MCP contract tests
  integration/     Integration flows
  unit/            Unit tests

Notes

• The layout is intentionally service-oriented, with the published user CLI separate from the server-side Admin CLI.
• Add new features under src/services and expose through src/transport.