Known Architecture Gaps

Known Architecture Gaps

Inconsistencies between the intended architecture and the current state. Use this as a backlog for future cleanup — not a list of blockers.

Last updated: 2026-Q2

---

1. Split feature boundary (in-app vs extracted package)

Problem: The repo still mixes app-local features and extracted feature packages, so contributors can still reach for the wrong home if they do not start from the canonical architecture docs.

Current state:

• Dashboard screen ownership is now defined in docs/architecture/07-feature-source-of-truth.md
• The live extracted feature packages are limited to feature-activity, feature-people, and feature-publications
• The remaining ambiguity is documentation adoption, not unresolved architecture

Resolution (2026-Q2): A canonical source-of-truth decision has been made for every feature. See 07-feature-source-of-truth.md and 17-feature-package-audit.md. The short rule: dashboard pages and screen composition are app-owned; reusable feature logic may stay in the small set of remaining packages/feature-* packages.

Status: ✅ Decided and documented.

---

2. Root src/monitoring/ — ✅ Resolved (2026-04-23)

Was: src/monitoring/tracing.ts existed at the repo root as a stale duplicate of packages/platform-ingestion/src/infra/telemetry/tracing.ts.

Resolution: Deleted src/monitoring/tracing.ts and the dead test tests/monitoring/tracing.test.ts. The canonical tracing implementation is packages/platform-ingestion/src/infra/telemetry/tracing.ts with co-located tests (tracing.test.ts, 9 tests). The root src/ directory is now empty and removed.

---

3. packages/utils — mixed concerns

Problem: packages/utils contains DOI normalization, D1 shard routing, and JSON Patch helpers — three unrelated concerns bundled under one vague name.

Current state: Works but grows in an unstructured way as new “shared utilities” are added without a clear ownership question.

Suggested resolution: Either:

• Split into focused sub-packages (@platform/doi, @platform/db-routing)
• Or enforce explicit module boundaries within utils/ using barrel files per concern and Oxlint import restrictions

---

4. apps/dashboard/src/lib/ — risk of accumulation

Problem: src/lib/ is documented in ARCHITECTURE.md as “not a dumping ground” but this rule is hard to enforce mechanically.

Current state: Minimal and clean, but without an Oxlint import-type rule, nothing prevents feature-specific code from drifting in.

Suggested resolution: Add an Oxlint no-restricted-imports override on src/lib/** that disallows imports from src/features/**.

---

5. plans/ and thoughts/ visibility

Problem: plans/ and thoughts/ directories sit at the repo root alongside docs/. They have a different lifecycle (temporary, non-canonical) but are not distinguished visually or structurally from committed documentation.

Current state: README does not distinguish between the three.

Suggested resolution:

• Add plans/ and thoughts/ as entries in .gitignore for feature branches where they are scratch space (but keep them in main for shared planning)
• OR move all in-flight plans to a GitHub Project or wiki

---

6. Legacy apps/ directories with no package.json

Problem: Three directories exist under apps/ that are not registered pnpm workspace packages and have no package.json:

• apps/legaciti.org/ — appears to predate apps/marketing/; contains src/content and a dist tree
• apps/my.legaciti.org/ — appears to predate apps/dashboard/; contains a nested apps/my.legaciti.org/ subtree (likely a wrangler artifact)
• apps/docs.legaciti.org/ — contains only build output; no source

Current state: These directories are silently included in pnpm-workspace.yaml (apps/*) but are ignored at install time because pnpm skips entries without package.json. They create noise in the repo tree and could confuse new contributors.

Suggested resolution:

1. Confirm apps/marketing/ covers all content that was in apps/legaciti.org/src/.
2. Confirm apps/dashboard/ is the canonical replacement for apps/my.legaciti.org/.
3. Delete all three directories once confirmed.

7. Worker apps outside the Turbo pipeline

Problem: workers/* are not in turbo.json and are deployed via raw wrangler deploy scripts. This means:

• No Turbo task caching for worker lint/test
• Worker deployments are not coordinated with the dashboard deploy
• New engineers may not know to look at scripts/deploy/ for worker deploys

Current state: Documented in AGENTS.md as intentional, but not explained. The reason is that wrangler’s deploy model does not fit Turbo’s caching model cleanly (workers cannot be built independently of CF infra state).

Suggested resolution: Add Turbo lint and type-check tasks for workers (they are safe to cache), but keep deploy outside the pipeline.

---

8. workers/my-api/ still present (DEPRECATED)

Problem: The deprecated worker (workers/my-api/) is still in the monorepo. It has been superseded by TanStack Start server functions in apps/dashboard. Keeping it causes:

• Confusion for new contributors
• False positive matches in global searches
• Extra pnpm workspace overhead

Current state: Marked DEPRECATED in AGENTS.md and copilot-instructions.md but not removed.

Suggested resolution: Confirm no production traffic routes to its domain, then delete workers/my-api/ and remove any remaining references. Run pnpm validate after removal to confirm no breakage.

---

Tracking

Open issues derived from this file should be tracked in the project issue tracker. When a gap is fully resolved, move it to an ADR in docs/adr/ describing the decision made.