Files
sharepoint-acc-sync/README.md

47 lines
3.7 KiB
Markdown

# SharePoint → ACC Sync
Keeps project folders in SharePoint mirrored into Autodesk Construction Cloud (ACC / Autodesk Forma Docs), with a few minutes' delay at most. One server can sync many projects. Each project pairs one SharePoint folder with one ACC folder.
There is also a small web page that shows each project's file tree, sync status, open issues and the last 7 days of sync history. It has a "Run now" button as well.
## What it does
- **One-way sync.** SharePoint is the source of truth. Nothing is ever written back to SharePoint.
- **Every file operation carries over.** Creates, edits (as new ACC versions), renames, moves and deletes are all mirrored. Removing something from the project's SharePoint root counts as deleting it.
- **Files added to ACC by hand are left alone.** The sync only ever changes ACC items it created.
- **Admins can leave folders out.** Every folder syncs by default. Unticking one on the project's admin page deletes the copies the sync made of it in ACC; ticking it again brings them back.
- **Temp and lock files are ignored.** That covers `~$*`, `*.tmp`, `Thumbs.db` and similar.
- **Failures are retried 3 times**, then reported as an issue on the status page.
## Status
In development. The sync engine, database, scheduler and web UI are built, and you can try them end to end in **simulated mode**. The real SharePoint/ACC connections come next, once credentials arrive. See:
- [docs/design.md](docs/design.md): architecture, interfaces, data model and build order
- [docs/access-setup.md](docs/access-setup.md): what IT and the ACC admin need to set up
- [docs/runbook.md](docs/runbook.md): deploying with Docker/Portainer, updating, backups, troubleshooting
## Running it locally
```sh
npm install
cp .env.example .env # simulated mode, admin login admin / change-me
npm run dev # http://localhost:5288
```
In simulated mode, SharePoint and ACC are in-memory stand-ins. A demo project is created at startup, filled with sample files, and edited at random every 45 seconds so there's something to watch. One file (`Models/Architectural/Corrupt model.rvt`) is always rejected, so the issues list has something in it. Nothing persists: a restart starts over.
| Command | What it does |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `npm test` | Unit and integration tests (Vitest) |
| `npm run check` | Type check |
| `npm run lint` | Prettier + ESLint |
| `npm run build` | Production build into `build/` (`node build` runs it; run it from the repo root so `drizzle/` migrations are found) |
| `npm run image:publish` | Checks, builds and pushes the Docker image to the Gitea registry (see the runbook) |
To try the Docker image locally: put `ADMIN_USERNAME`, `ADMIN_PASSWORD`, `SESSION_SECRET`, `SYNC_BACKEND=simulated` and `ORIGIN=http://localhost:3288` in `.env`, then run `docker compose up -d --build` and open http://localhost:3288.
## Stack
SvelteKit (TypeScript) on `adapter-node`, running as a single long-lived Docker container. It stores its state in SQLite on a mounted volume. It talks to Microsoft Graph for SharePoint and to the Autodesk Platform Services (APS) Data Management API for ACC.