Notizarr/docs/phase1/07-folder-structure.md

07 — Folder Structure

Two different structures matter here: the source repository (this working directory, developed on Windows, deployed to Unraid) and the Unraid runtime directory the user specified. They're linked by the compose file and the built Docker image, not by being the same directory.

Source repository (Y:\notizarr, this directory)

notizarr/
├── apps/
│   ├── server/                  # Node.js + TypeScript backend (Fastify)
│   │   ├── src/
│   │   │   ├── modules/
│   │   │   │   ├── auth/
│   │   │   │   ├── users/
│   │   │   │   ├── topics/
│   │   │   │   ├── notifications/
│   │   │   │   ├── tokens/
│   │   │   │   ├── push/
│   │   │   │   ├── admin/
│   │   │   │   ├── audit/
│   │   │   │   └── rate-limit/
│   │   │   ├── db/
│   │   │   │   ├── schema.ts
│   │   │   │   └── migrations/
│   │   │   ├── plugins/         # fastify plugins: auth, csrf, cors, logging, metrics
│   │   │   ├── listeners/       # web.ts (8080), ingest.ts (8081)
│   │   │   └── index.ts
│   │   ├── healthcheck.js
│   │   ├── Dockerfile
│   │   └── package.json
│   └── web/                     # React + TypeScript + Vite frontend
│       ├── src/
│       │   ├── routes/
│       │   ├── components/
│       │   ├── hooks/
│       │   ├── lib/
│       │   └── service-worker/  # custom push/notificationclick handlers (injectManifest)
│       ├── public/
│       │   └── icons/
│       ├── vite.config.ts
│       └── package.json
├── packages/
│   └── shared/                  # types shared between server and web (API request/response shapes)
├── docker/
│   ├── docker-compose.yml       # dev-oriented compose (hot reload)
│   └── docker-compose.prod.yml  # reference for the Unraid deployment
├── docs/
│   ├── phase1/                  # this design package
│   ├── migration-ntfy.md        # written in Phase 9
│   └── home-assistant.md        # written in Phase 9
├── .env.example
├── package.json                 # npm/pnpm workspaces root
└── README.md

Unraid deployment directory (/mnt/tank/appdata/notizarr)

This is runtime state + the deployment compose file, not the source tree:

/mnt/tank/appdata/notizarr/
├── docker-compose.yml   # copy of docker/docker-compose.prod.yml (or generated by a deploy step)
├── .env                 # real secrets — never committed to the repo
├── app/                 # bind mount → /data in the notizarr container (reserved, unused in v1)
├── postgres/            # bind mount → Postgres data directory
├── backups/             # pg_dump output lands here
└── logs/                # optional, only used if file logging is enabled

Deploying an update is: build/pull the notizarr image, git pull (or copy) the updated docker-compose.yml into this directory if it changed, then docker compose up -d from here.