README.md

README.md

1. # Meridian Ops Board
3. An operations dashboard and daily AI briefing for a small print and display
4. shop. It pulls orders, CRM leads and tasks, EOS to-dos, a content tracker,
5. meeting action items and the shared inboxes into one page per person, and has
6. a language model write each person a morning briefing from the same data.
8. **Everything about the company is fictional.** Meridian Display Co., its staff,
9. its clients, its orders and every piece of data in this repository are
10. invented. The system itself is real: it was designed and built with
11. AI-assisted development and ran in daily use, and this is a rebuild of it with
12. sample data.
14. ## What it shows
16. - **The people board.** Who is loaded and who is not, per person, across every
17. source. A person no source covers reads "not tracked", never zero.
18. - **My Day.** Each person's own orders, tasks, to-dos and meeting commitments,
19. with a private task list only they can read.
20. - **The shared inbox.** Every role mailbox in one view, with role-gated reply
21. and send, a confirmation step and an audit record.
22. - **The morning briefing.** A distilled payload goes to a language model, which
23. writes a company briefing and a personal day plan for each person, tiered by
24. role.
25. - **Onboarding.** A training plan and an end-of-day note for a new hire, visible
26. only to the people who should see it.
27. - **Data health.** Which sources answered, which failed, and what nothing covers.
29. ## How it is built
31. A pnpm monorepo in TypeScript, with one Python script for the briefing.
33. | Part | Where |
34. |---|---|
35. | API clients for Plinth, Bitrix24, Ninety, Google Sheets, Fathom and Gmail | `packages/` |
36. | Collect, view model and page rendering | `apps/dashboard/` |
37. | Cloudflare Worker: cron sync, Access-verified pages, the inbox, D1 | `apps/worker/` |
38. | Rosters, stage taxonomies, grants and other human-edited config | `config/` |
39. | The briefing, the only place a model is called | `analysis/brief.py` |
41. The design rules the code follows, starting with "zero, null and broken must
42. never look the same", are in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
44. ## Running it
46. Node 22.5 or later and pnpm 9. The D1 store tests run on `node:sqlite`, which
47. older Node does not have; below 22.5 they skip with a warning rather than fail.
49. ```bash
50. pnpm install
51. pnpm test # 1,168 TypeScript and 49 Python cases, offline
52. pnpm typecheck
53. pnpm dashboard --fixtures # writes dashboard.html from sample data
54. ```
56. CI (`.github/workflows/ci.yml`) runs install, typecheck and test on Node 22.
57. Live runs need credentials in the process environment; see
58. `credentials.example.sh`. There is deliberately no `.env` reader. The
59. briefing (`analysis/brief.py`) calls a local OpenAI-compatible server at
60. `http://127.0.0.1:1234/v1` by default. Pointing `ANTHROPIC_BASE_URL` at the
61. Anthropic API switches it to that API, which needs `ANTHROPIC_API_KEY`.
63. ## Deploying the Worker
65. ```bash
66. cd apps/worker # once per account
67. wrangler kv namespace create DASHBOARD # and again with --preview
68. wrangler d1 create meridian-checkins
69. wrangler d1 migrations apply meridian-checkins --remote
70. wrangler secret put NINETY_TOKEN # also BITRIX_WEBHOOK_URL, PLINTH_API_KEY
71. wrangler deploy
72. ```
74. Paste the printed KV and D1 ids into `wrangler.jsonc`. Gmail credentials are
75. Worker secrets too (`pnpm inbox:auth` mints and stores a mailbox's token).
76. Put a Cloudflare Access application in front of the `workers.dev` URL and its
77. preview URLs, then set `ACCESS_TEAM_DOMAIN` and `ACCESS_AUD` in
78. `wrangler.jsonc`: until both are set the Worker refuses every request.
79. `pnpm morning` syncs, writes the briefings and pushes the pages to the Worker.