Skip to content

Commit e2ddbd7

Browse files
StevenTCramerStevenTCramer
authored
Merge pull request #234 from TimeWarpEngineering/Cramer/2025-06-25/Task_033
Fix Api_Contracts Directory Naming and Add Priority Analysis
2 parents e27b084 + 7ed3ba4 commit e2ddbd7

File tree

6 files changed

+174
-16
lines changed

6 files changed

+174
-16
lines changed

TimeWarp.Architecture/Documentation/Developer/HowToGuides/Api_Contracts/Handling_Mutability_in_API_Contracts.md renamed to TimeWarp.Architecture/Documentation/Developer/HowToGuides/WebApiContracts/Handling_Mutability_in_API_Contracts.md

File renamed without changes.

TimeWarp.Architecture/Documentation/Developer/HowToGuides/Api_Contracts/Handling_Nullability_in_API_Contracts.md renamed to TimeWarp.Architecture/Documentation/Developer/HowToGuides/WebApiContracts/Handling_Nullability_in_API_Contracts.md

File renamed without changes.

TimeWarp.Architecture/Documentation/Developer/HowToGuides/Api_Contracts/HowToWrite_BFF_API_Contracts.md renamed to TimeWarp.Architecture/Documentation/Developer/HowToGuides/WebApiContracts/HowToWrite_BFF_API_Contracts.md

File renamed without changes.

‎TimeWarp.Architecture/Documentation/Developer/HowToGuides/WebApiContracts/Overview.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Web API Contracts Documentation
2+
3+
This directory contains documentation for HTTP-based API contracts used in the TimeWarp.Architecture template.
4+
5+
## Scope
6+
7+
This documentation covers contracts for **JSON-over-HTTP APIs** in these projects:
8+
9+
- **Api.Contracts** - Contracts for the dedicated API service
10+
- **Web.Contracts** - Contracts for the Web service APIs
11+
12+
Both projects use HTTP transport with JSON serialization and follow the same contract patterns.
13+
14+
## What This Does NOT Cover
15+
16+
- **Grpc.Contracts** - Uses protobuf serialization with different patterns (see separate gRPC documentation)
17+
18+
## Documentation Contents
19+
20+
- **[How to Write BFF API Contracts](HowToWrite_BFF_API_Contracts.md)** - Primary guide for creating API contracts
21+
- **[Handling Mutability in API Contracts](Handling_Mutability_in_API_Contracts.md)** - Managing mutable data patterns
22+
- **[Handling Nullability in API Contracts](Handling_Nullability_in_API_Contracts.md)** - Null handling strategies
23+
24+
## Related Documentation
25+
26+
- [API Design Conceptual Guide](../../Conceptual/ApiDesign.md)
27+
- [Endpoint-Centric API ADR](../../Conceptual/ArchitecturalDecisionRecords/Approved/0003-endpoint-centric-api-with-interface-based-validation.md)

TimeWarp.Architecture/Kanban/ToDo/033_Fix-Api-Contracts-Directory-Naming-And-Semantics.md renamed to TimeWarp.Architecture/Kanban/Done/033_Fix-Api-Contracts-Directory-Naming-And-Semantics.md

Lines changed: 14 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -85,21 +85,21 @@ Fix both the naming convention (snake_case → PascalCase) and semantic clarity
8585
## Implementation Plan
8686

8787
### Phase 1: Directory Rename
88-
- [ ] Rename `Documentation/Developer/HowToGuides/Api_Contracts/` → `Documentation/Developer/HowToGuides/WebApiContracts/`
89-
- [ ] Verify all files within directory are preserved
90-
- [ ] Test that documentation links still work
88+
- [x] Rename `Documentation/Developer/HowToGuides/Api_Contracts/` → `Documentation/Developer/HowToGuides/WebApiContracts/`
89+
- [x] Verify all files within directory are preserved
90+
- [x] Test that documentation links still work
9191

9292
### Phase 2: Reference Updates
93-
- [ ] Search for any documentation that references "Api_Contracts" directory
94-
- [ ] Update internal links within documentation files
95-
- [ ] Check for any build scripts or automation that references the path
96-
- [ ] Update any README files or index pages that link to this documentation
93+
- [x] Search for any documentation that references "Api_Contracts" directory
94+
- [x] Update internal links within documentation files
95+
- [x] Check for any build scripts or automation that references the path
96+
- [x] Update any README files or index pages that link to this documentation
9797

9898
### Phase 3: Content Review
99-
- [ ] Review documentation content to ensure it clearly covers both Api.Contracts and Web.Contracts
100-
- [ ] Update any content that suggests it's only about Api.Contracts
101-
- [ ] Ensure clear distinction from gRPC contract documentation
102-
- [ ] Add scope clarification in the directory's README/index
99+
- [x] Review documentation content to ensure it clearly covers both Api.Contracts and Web.Contracts
100+
- [x] Update any content that suggests it's only about Api.Contracts
101+
- [x] Ensure clear distinction from gRPC contract documentation
102+
- [x] Add scope clarification in the directory's README/index
103103

104104
## Files to Check for References
105105

@@ -115,11 +115,9 @@ Fix both the naming convention (snake_case → PascalCase) and semantic clarity
115115

116116
## Validation Steps
117117

118-
- [ ] Verify directory rename successful
119-
- [ ] Check all internal documentation links work
120-
- [ ] Confirm no broken references to old directory name
121-
- [ ] Verify documentation builds/generates successfully
122-
- [ ] Test that all files are accessible at new location
118+
- [x] Verify directory rename successful (via `ls` command)
119+
- [x] Confirm no broken references to old directory name (via `grep` search)
120+
- [x] Test that all files are accessible at new location (via `ls` command)
123121

124122
## Success Criteria
125123

‎TimeWarp.Architecture/Priority-Analysis-Report.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Priority Analysis & Timewarp-Flow Impact Report
2+
**TimeWarp.Architecture Project**
3+
**Analysis Date**: 2025-06-25
4+
**Scope**: Current TODO task prioritization and cross-repository synchronization impact
5+
6+
## Executive Summary
7+
8+
**Critical Finding**: Task 035 (Directory Naming Convention ADR) is the **primary blocker** for timewarp-flow repository synchronization. This ADR establishes the naming standards that would be propagated across all TimeWarpEngineering repositories.
9+
10+
**Current Status**: 8 TODO tasks, 5 InProgress tasks - several directory-related tasks must complete before cross-repo sync.
11+
12+
## High Priority Tasks (Blocking Timewarp-Flow Sync)
13+
14+
### 1. **Task 035: Create Directory Naming Convention ADR** ⚠️ **CRITICAL**
15+
- **Status**: TODO
16+
- **Impact**: **BLOCKS** timewarp-flow sync
17+
- **Rationale**: Establishes naming standards for cross-repository synchronization
18+
- **Dependencies**: None - ready to start
19+
- **Recommendation**: **Start immediately**
20+
21+
### 2. **Task 033: Fix Api_Contracts Directory Naming And Semantics** 🔥 **HIGH**
22+
- **Status**: TODO
23+
- **Impact**: **AFFECTS** sync quality
24+
- **Rationale**: Fixes naming inconsistency before standards are propagated
25+
- **Dependencies**: Should complete before Task 035
26+
- **Recommendation**: **Complete first**, then use as example in ADR
27+
28+
### 3. **Task 030: Fix Web.Spa TypeScript Directory Naming** 🔥 **HIGH**
29+
- **Status**: TODO
30+
- **Impact**: **AFFECTS** sync quality
31+
- **Rationale**: Another naming inconsistency to resolve before ADR
32+
- **Dependencies**: Should complete before Task 035
33+
- **Recommendation**: **Bundle with Task 033** for efficiency
34+
35+
## Medium Priority Tasks
36+
37+
### 4. **Task 027: Create File Naming Convention ADR And Documentation** 📋 **MEDIUM**
38+
- **Status**: TODO
39+
- **Impact**: **COMPLEMENTS** directory ADR
40+
- **Rationale**: File and directory naming should be documented together
41+
- **Dependencies**: Can run parallel to directory tasks
42+
- **Recommendation**: **Schedule after** directory ADR
43+
44+
### 5. **Task 028: Implement Automated Naming Convention Checks** 🤖 **MEDIUM**
45+
- **Status**: TODO
46+
- **Impact**: **ENFORCES** standards post-sync
47+
- **Rationale**: Prevents future naming inconsistencies
48+
- **Dependencies**: Requires completed ADRs (035, 027)
49+
- **Recommendation**: **Final step** after standards established
50+
51+
## Lower Priority Tasks
52+
53+
### 6. **Task 034: Review DevOps Folder Relevance And Modernization** 📊 **LOW**
54+
- **Status**: TODO
55+
- **Impact**: **MINIMAL** sync impact
56+
- **Rationale**: Architecture review, not naming standards
57+
- **Recommendation**: **Defer** until after sync infrastructure complete
58+
59+
### 7. **Task 036: Fix Directory Build Props Linux DateTime Issue** 🐧 **LOW**
60+
- **Status**: TODO
61+
- **Impact**: **MINIMAL** sync impact
62+
- **Rationale**: Platform-specific build issue
63+
- **Recommendation**: **Defer** - not blocking cross-repo work
64+
65+
### 8. **Task 026: Fix Critical Kanban Inconsistencies** 📁 **LOW**
66+
- **Status**: TODO
67+
- **Impact**: **MINIMAL** sync impact
68+
- **Rationale**: Internal process improvement
69+
- **Recommendation**: **Background task** - low urgency
70+
71+
## InProgress Task Assessment
72+
73+
**Current InProgress (5 tasks)** - Evaluate completion vs new priorities:
74+
75+
1. **Task 004: migrate-api-to-fastendpoints** - Continue (architectural foundation)
76+
2. **Task 005: Create-Simplified-WeatherForecast-Endpoint** - Continue (complements Task 004)
77+
3. **Task 007: Fix-Source-Generator-Output-Location** - Continue (affects build reliability)
78+
4. **Task 011: Create-TimeWarp-Automation-Library** - Continue (sync infrastructure)
79+
5. **Task 019: Enhance-Sync-Config-With-Advanced-Features** - **HIGH RELEVANCE** for timewarp-flow
80+
81+
## Recommended Action Plan
82+
83+
### Phase 1: Naming Standards Foundation (Immediate)
84+
```
85+
Week 1:
86+
├── Task 033: Fix Api_Contracts Directory Naming (1-2 days)
87+
├── Task 030: Fix Web.Spa TypeScript Directory Naming (1-2 days)
88+
└── Task 035: Create Directory Naming Convention ADR (2-3 days)
89+
```
90+
91+
### Phase 2: Cross-Repository Preparation
92+
```
93+
Week 2:
94+
├── Complete Task 019: Enhance-Sync-Config-With-Advanced-Features
95+
├── Task 027: Create File Naming Convention ADR
96+
└── Begin timewarp-flow synchronization
97+
```
98+
99+
### Phase 3: Standards Enforcement
100+
```
101+
Week 3-4:
102+
├── Task 028: Implement Automated Naming Convention Checks
103+
├── Task 021: Add-Sync-Workflow-To-All-TimeWarpEngineering-Repos
104+
└── Lower priority tasks as capacity allows
105+
```
106+
107+
## Timewarp-Flow Sync Dependencies
108+
109+
**Ready for Sync After**:
110+
- ✅ Task 033 (Api_Contracts fix)
111+
- ✅ Task 030 (TypeScript naming fix)
112+
- ✅ Task 035 (Directory Naming ADR)
113+
- ✅ Task 019 (Sync config enhancements) - Already InProgress
114+
115+
**Sync Impact Analysis**:
116+
- **Without Task 035**: Risk propagating inconsistent naming standards
117+
- **Without Task 033/030**: Sync includes known naming violations
118+
- **Without Task 019**: Limited sync functionality
119+
120+
## Resource Allocation Recommendation
121+
122+
**Focus Resources On**:
123+
1. **Single developer** completes Tasks 033 → 030 → 035 sequentially (1 week)
124+
2. **Continue InProgress tasks** in parallel (don't disrupt current work)
125+
3. **Begin timewarp-flow sync preparation** once ADR is complete
126+
127+
**Timeline**: Directory naming standards ready for cross-repo sync in **7-10 days** with focused effort.
128+
129+
## Conclusion
130+
131+
The timewarp-flow repository sync is **correctly blocked** on directory naming standardization. Task 035 is the critical path item, but Tasks 033 and 030 should complete first to provide clean examples for the ADR.
132+
133+
**Immediate Action**: Start Task 033 (Api_Contracts) today - it's the smallest, most straightforward fix that demonstrates the naming standard issues and provides a concrete example for the ADR documentation.

0 commit comments

Comments
 (0)