Skip to content

Commit 9ea9aab

Browse files
kryputhkryputh
authored
Merge pull request Stellar-Mail#1807 from Esc1200/fix/449-sla-architecture
docs(tools): establish SLA Deadline Tracker architecture & folder contract
2 parents 34e74f3 + 8ecb9a8 commit 9ea9aab

5 files changed

Lines changed: 289 additions & 26 deletions

File tree

‎tools/v1/team/sla-deadline-tracker/ARCHITECTURE.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# SLA Deadline Tracker — Architecture
2+
3+
This document is the folder-local architecture plan for the SLA Deadline
4+
Tracker (issue #449). It defines module boundaries, data ownership,
5+
dependencies, and integration constraints. It does **not** modify the main
6+
application and is intended to be reviewed as a self-contained mini-product
7+
change. The functional core is implemented separately in #450
8+
(`services/slaTracker.ts`); this document describes how the folder is organized
9+
around that core and what future contributors may build on top of it.
10+
11+
## 1. Goal & scope
12+
13+
The tool monitors response-SLA status for a collection of tracked items
14+
(emails, tickets, conversations). It is a **V1, team-audience** mini-product.
15+
It is built in isolation and must not be wired into the main application until a
16+
future integration issue explicitly allows it.
17+
18+
## 2. Folder layout
19+
20+
```
21+
tools/v1/team/sla-deadline-tracker/
22+
├── types/ # shared TypeScript contracts (no logic, no imports)
23+
├── services/ # framework-free business logic (the SLA engine)
24+
├── fixtures/ # deterministic local sample data (no production data)
25+
├── hooks/ # (planned) React glue — NOT implemented yet
26+
├── components/ # (planned) UI — NOT implemented yet
27+
├── tests/ # vitest unit tests for services/fixtures
28+
├── docs/ # CORE.md (engine notes), ARCHITECTURE.md (this file)
29+
├── index.ts # public API surface (re-exports types + engine)
30+
├── vitest.config.ts # isolated tool test config
31+
└── specs.md # tool specification + contributor change rules
32+
```
33+
34+
The dependency flow is strictly one-way:
35+
36+
```
37+
components/ → hooks/ → services/ → types/
38+
(planned) (planned) (built) (built)
39+
```
40+
41+
Nothing outside this folder may be imported, and nothing inside this folder may
42+
import from the main app.
43+
44+
## 3. Module boundaries
45+
46+
| Module | Status | Responsibility | May import |
47+
| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
48+
| `types/` | built | Shared interfaces (`SlaTrackedItem`, `SlaPolicy`, `SlaEvaluation`, `SlaSummary`, `SlaStatus`). No logic. | nothing |
49+
| `services/` | built | Pure, deterministic SLA engine (`evaluateSla`, `summarizeSla`, `computeDeadline`). Time injected for reproducibility. | `../types/` only |
50+
| `fixtures/` | built | Deterministic sample items + standard policy for tests. | `../types/` |
51+
| `tests/` | built | vitest specs covering every status branch, determinism, large arrays. | `../services/`, `../fixtures/`, `../types/` |
52+
| `hooks/` | planned | Future React glue (loading/error state around the service). | React, `../services/`, `../types/` |
53+
| `components/` | planned | Future presentational UI (status badges, deadline lists). | `../hooks/`, `../types/` |
54+
55+
Full per-module contracts are in `MODULE_BOUNDARIES.md`.
56+
57+
## 4. Data ownership
58+
59+
- **Source of truth for policy:** `fixtures/sla.fixture.ts` ships a
60+
`STANDARD_SLA_POLICY` (4h response budget, 30m warn window). Real deployments
61+
will supply policy at call time; the engine never stores policy itself.
62+
- **Items are caller-owned:** `SlaTrackedItem` records are produced and
63+
persisted by the _future integrating_ code. This folder only _reads_ them via
64+
the engine; it owns no storage, no database schema, and no network calls.
65+
- **No PII leakage path:** the engine emits only status + numeric remaining
66+
time. It never serializes item bodies or recipient identities outside the
67+
folder.
68+
69+
## 5. Dependencies
70+
71+
- **Runtime deps:** none beyond TypeScript. No external SDK, no network client.
72+
- **Test deps:** `vitest` (dev-only, via the folder's `vitest.config.ts`).
73+
- **Forbidden:** any import crossing into `src/`, the app shell, routing, inbox
74+
architecture, wallet/Stellar core, or the design system.
75+
76+
## 6. Integration constraints
77+
78+
- The tool is **isolated until a future integration issue links it.** Do not add
79+
routes, navigation entries, or app-store wiring here.
80+
- If a future issue connects this tool to the mail app, it must do so by
81+
importing the public API from `index.ts` and adapting items into
82+
`SlaTrackedItem` at the boundary — never by reaching into `services/`
83+
internals or mutating the engine's signatures.
84+
- Time must always be supplied by the caller (`now` parameter) so evaluations
85+
stay deterministic and testable; do not introduce `Date.now()` inside the
86+
engine.
87+
88+
## 7. What future contributors may and may not change
89+
90+
See `specs.md` → "Contributor change rules" for the explicit allow/deny list.

‎tools/v1/team/sla-deadline-tracker/MODULE_BOUNDARIES.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# SLA Deadline Tracker — Module Boundaries
2+
3+
This document defines the internal contracts, public interfaces, and dependency
4+
rules for each module inside the SLA Deadline Tracker tool. The tool is a V1,
5+
team-audience mini-product for response-SLA monitoring. It is built in
6+
isolation and is not wired into the main application yet.
7+
8+
## 1. Module: Types (shared contracts)
9+
10+
Location: `types/index.ts`.
11+
12+
Responsibility: declares the shared TypeScript interfaces used across the tool.
13+
Owns no logic and imports nothing.
14+
15+
Public API:
16+
17+
export interface SlaTrackedItem {
18+
id: string;
19+
label: string;
20+
startedAt: string; // ISO-8601
21+
deadlineAt: string | null;
22+
responded: boolean;
23+
respondedAt: string | null;
24+
}
25+
26+
export interface SlaPolicy {
27+
responseBudgetMs: number;
28+
warnWindowMs: number;
29+
}
30+
31+
export type SlaStatus = "responded" | "on-track" | "due-soon" | "breached";
32+
33+
export interface SlaEvaluation {
34+
itemId: string;
35+
status: SlaStatus;
36+
remainingMs: number;
37+
breached: boolean;
38+
responded: boolean;
39+
}
40+
41+
export interface SlaSummary {
42+
total: number;
43+
responded: number;
44+
onTrack: number;
45+
dueSoon: number;
46+
breached: number;
47+
}
48+
49+
Dependencies: no imports from `services/`, `hooks/`, `components/`, or the main
50+
application.
51+
52+
## 2. Module: Services (business logic)
53+
54+
Location: `services/slaTracker.ts`.
55+
56+
Responsibility: encapsulates all framework-free SLA logic — per-item status
57+
evaluation, aggregate summarization, and deadline computation. The engine is
58+
pure and deterministic; time is injected (`now`) so evaluations are
59+
reproducible. Services never import React and never reach outside this folder.
60+
61+
Public API:
62+
63+
export function evaluateSla(
64+
item: SlaTrackedItem,
65+
policy: SlaPolicy,
66+
now: number,
67+
): SlaEvaluation;
68+
69+
export function summarizeSla(
70+
items: readonly SlaTrackedItem[],
71+
policy: SlaPolicy,
72+
now: number,
73+
): SlaSummary;
74+
75+
export function computeDeadline(
76+
startedAt: string,
77+
policy: SlaPolicy,
78+
): string;
79+
80+
Dependencies:
81+
82+
- Allowed to import: TypeScript types from `../types/`.
83+
- Forbidden: React or hooks, presentational components, main app stores or
84+
APIs, any networking, and any use of `Date.now()` inside the engine (callers
85+
supply `now`).
86+
87+
## 3. Module: Fixtures (deterministic sample data)
88+
89+
Location: `fixtures/sla.fixture.ts`.
90+
91+
Responsibility: provides deterministic sample items and a standard policy for
92+
tests. No production data, no network.
93+
94+
Public API:
95+
96+
export const STANDARD_SLA_POLICY: SlaPolicy;
97+
export const FIXED_NOW: number;
98+
export const SAMPLE_ITEMS: SlaTrackedItem[];
99+
100+
Dependencies: allowed to import types from `../types/` only.
101+
102+
## 4. Module: Tests
103+
104+
Location: `tests/slaTracker.test.ts`.
105+
106+
Responsibility: unit coverage for the engine — every `SlaStatus` branch,
107+
determinism, large-array single-pass behavior, and deadline math.
108+
109+
Dependencies: allowed to import `../services/`, `../fixtures/`, `../types/`.
110+
Forbidden to import anything outside the folder or the main app.
111+
112+
## 5. Module: Hooks (React integration) — PLANNED, not implemented
113+
114+
Location: `hooks/` (future).
115+
116+
Responsibility (when built): synchronize the service with React components,
117+
managing the item list, loading/error state, and time-relative refreshes. Hooks
118+
must obtain `now` from a clock source and pass it into the engine; they must not
119+
introduce their own SLA math.
120+
121+
Intended public shape:
122+
123+
export function useSlaTracker(
124+
items: SlaTrackedItem[],
125+
policy: SlaPolicy,
126+
): { summary: SlaSummary; evaluations: SlaEvaluation[]; refresh: () => void };
127+
128+
Dependencies (when built): allowed to import React hooks, the service from
129+
`../services/`, and types from `../types/`. Forbidden: presentational
130+
components and core app state contexts.
131+
132+
## 6. Module: Components (user interface) — PLANNED, not implemented
133+
134+
Location: `components/` (future).
135+
136+
Responsibility (when built): renders status badges, deadline lists, and
137+
breach alerts. Components stay presentational and delegate all logic to the
138+
hook.
139+
140+
Dependencies (when built): allowed to import hooks from `../hooks/` and types
141+
from `../types/`. Forbidden: core app features, layout navigation, or importing
142+
service functions directly.
143+
144+
## 7. Public API surface
145+
146+
Location: `index.ts` — re-exports the engine and types. Future UI/integration
147+
work should import **only** from `index.ts`, never from `services/` internals.
148+
149+
## Import rules checklist
150+
151+
- [ ] Only import from files inside `tools/v1/team/sla-deadline-tracker/`.
152+
- [ ] Maintain a one-way dependency flow: components → hooks → services → types.
153+
- [ ] No circular dependencies.
154+
- [ ] All shared interfaces are imported from `types/`.
155+
- [ ] No path may ever import from `src/`, the app shell, routing, inbox
156+
architecture, wallet/Stellar core, or the design system.
157+
- [ ] The engine never calls `Date.now()`; `now` is always supplied by the
158+
caller.

‎tools/v1/team/sla-deadline-tracker/components/.gitkeep‎

Whitespace-only changes.

‎tools/v1/team/sla-deadline-tracker/hooks/.gitkeep‎

Whitespace-only changes.

‎tools/v1/team/sla-deadline-tracker/specs.md‎

Lines changed: 41 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,56 @@
1-
# SLA Deadline Tracker
1+
# SLA Deadline Tracker — Specs
22

3-
Response deadline monitoring.
3+
Response deadline monitoring for a team's tracked items (emails, tickets,
4+
conversations). This is a self-contained, V1, team-audience tooling workspace.
45

56
## Scope
67

7-
- Release tier: $(System.Collections.Hashtable.Tier.ToUpperInvariant())
8-
- Audience: $(System.Collections.Hashtable.Audience)
9-
- Folder ownership: $dir/
8+
- Release tier: V1
9+
- Audience: team
10+
- Folder ownership: `tools/v1/team/sla-deadline-tracker/`
1011

11-
This is a self-contained tooling workspace. Do not wire this tool into the main app, routing, inbox architecture, wallet core, Stellar core, or design system unless a future integration issue explicitly allows it.
12+
Do not wire this tool into the main app, routing, inbox architecture, wallet
13+
core, Stellar core, or design system unless a future integration issue
14+
explicitly allows it.
1215

13-
Recommended internal structure:
16+
## Purpose
1417

15-
- components/
16-
- services/
17-
- hooks/
18-
- ests/
19-
- docs/
20-
"@ | Set-Content -Path "tools/v1/team/sla-deadline-tracker/README.md"
21-
@"
18+
Monitor response-SLA status across a collection of tracked items and surface
19+
which are on-track, due-soon, or breached, plus an aggregate view.
2220

23-
# SLA Deadline Tracker Specs
21+
## Architecture
2422

25-
## Purpose
23+
See `ARCHITECTURE.md` for the folder plan and `MODULE_BOUNDARIES.md` for
24+
per-module contracts and import rules. The functional core lives in
25+
`services/slaTracker.ts` (implemented in #450); this issue (#449) establishes
26+
the folder contract only.
27+
28+
## Required issue categories (this tool)
2629

27-
Response deadline monitoring.
30+
- Architecture ✅ (this issue)
31+
- Feature (core engine — #450)
32+
- UI and accessibility (planned)
33+
- Security and performance (planned)
34+
- Testing and documentation (ongoing)
2835

29-
## Contributor boundary
36+
## Contributor change rules
3037

31-
All work for this tool should stay in:
38+
**May change (inside this folder only):**
3239

33-
$dir/
40+
- Add or adjust pure logic in `services/` as long as it stays framework-free and
41+
time is injected (`now`), not `Date.now()`.
42+
- Add fixtures, tests, and docs under `fixtures/`, `tests/`, `docs/`.
43+
- Extend `types/` with new interfaces, keeping existing fields backward
44+
compatible for `index.ts` consumers.
45+
- Implement the planned `hooks/` and `components/` modules following
46+
`MODULE_BOUNDARIES.md`.
3447

35-
## Required issue categories
48+
**May NOT change:**
3649

37-
- Architecture
38-
- Feature
39-
- UI and accessibility
40-
- Security and performance
41-
- Testing and documentation
50+
- Any file outside `tools/v1/team/sla-deadline-tracker/`.
51+
- The main application shell, dashboard layout, navigation, authentication,
52+
wallet core, mail rendering engine, existing inbox architecture, routing,
53+
Stellar integration core, database schema, or design system.
54+
- The engine's public signatures in `index.ts` without a coordinated update to
55+
the integration boundary.
56+
- Introduce network calls, secrets, or production data into the folder.

0 commit comments

Comments
 (0)