# MeshVault

MeshVault is a self-hosted 3D model library being built as a Docker service.
It catalogs logical models containing STL parts, images and supplementary documents.

**Status:** M0 foundations only. There is no runnable web application, database
schema or Docker stack yet. Installation and a verified application quick start
are deliverables of [M1](https://git.keithsolomon.net/keith/MeshVault/milestones).
Do not deploy this scaffold as a service.

## Planned MVP

- Managed imports copy existing collections without changing their originals.
  Read-only source directories are supported; the managed destination must be writable.
- Physical folder browsing and management mirror the managed directory tree.
- Imports provide a pre-scan, progress and per-file failure reasons.
- Logical models support multiple files, categories, tags, notes, source URLs
  and uploaded thumbnails, with name/tag search and downloads.
- Catalog removal deletes database records only, retaining physical files.
- Missing files, changed content and exact duplicates are visible for user resolution.
  There is no automatic deletion or merging.

`Date added` records entry into MeshVault, not filesystem creation. File modification
times and sizes are separate metadata; MVP has no separate creation-date field.
Changed content is flagged **Updated**, with user acknowledgement re-baselining its
hash. No historical contents are preserved: an external overwrite cannot be undone
by detecting it. Backups must include PostgreSQL metadata, library files and uploaded
media as a consistent set using standard database/filesystem tools.

Other mesh formats, generated thumbnails, 3D viewing, watching, versioning, printer
management, external imports, AI and multi-user libraries are outside MVP.

## Architecture and decisions

Docker, PostgreSQL and PHP application logic; PHP-rendered templates with Tailwind
CSS and browser JavaScript. Node is planned for asset builds, with mesh processing
introduced only when those future features are scoped. No PHP framework is selected.

Accepted decisions: [managed storage (#1)](https://git.keithsolomon.net/keith/MeshVault/issues/1),
[dates (#2)](https://git.keithsolomon.net/keith/MeshVault/issues/2),
and [changed files (#3)](https://git.keithsolomon.net/keith/MeshVault/issues/3).
Tracking lives in [issues](https://git.keithsolomon.net/keith/MeshVault/issues).
Local planning notes and ADR copies are deliberately not versioned.

## Repository layout

| Directory | Responsibility |
| --- | --- |
| `src/` | PHP application and domain code |
| `public/` | Future HTTP document root and generated browser assets |
| `db/migrations/` | Ordered PostgreSQL schema migrations |
| `docker/` | Future container definitions and service configuration |
| `assets/` | Source assets, including the project icon |
| `tests/` | Automated checks and future application fixtures/tests |

Directory READMEs describe boundaries; they are not application implementations.

## Development checks

With PHP 8.3+ and Composer 2 installed:

```sh
composer install --no-interaction
composer validate --strict
composer lint
composer test
```

These commands validate foundation files and PSR-12 configuration, not application
behavior. See [CONTRIBUTING.md](CONTRIBUTING.md) for conventions and test limitations.
Container-based development, migrations and frontend build commands arrive in M1.

## License

MeshVault is licensed under **GNU AGPL version 3 only** (`AGPL-3.0-only`).
See [LICENSE](LICENSE) for the complete terms, including source availability
requirements for modified versions used interactively over a network.