Skip to content

Commit 799ff68

Browse files
StevenTCramerStevenTCramer
authored
Merge pull request #219 from TimeWarpEngineering/Cramer/2025-06-18/Task_019
Update documentation workflow and add root CLAUDE.md
2 parents 912ecd0 + 66ec760 commit 799ff68

2 files changed

Lines changed: 152 additions & 10 deletions

File tree

‎.github/workflows/timewarp-architecture-documentation.yml‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -39,42 +39,43 @@ jobs:
3939
- run: echo "🔎 The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}."
4040

4141
- name: Check out repository code
42-
uses: actions/checkout@v3
42+
uses: actions/checkout@v4
4343
- run: echo "💡 The ${{ github.repository }} repository has been cloned to the runner."
4444

4545
- name: List files in the repository
4646
run: |
4747
ls ${{ github.workspace }}
4848
4949
- name: Setup .NET
50-
uses: actions/setup-dotnet@v2
50+
uses: actions/setup-dotnet@v4
5151
with:
52-
dotnet-version: 7.0.x
52+
dotnet-version: 9.0.x
5353

5454
- name: Setup DocFX
55-
uses: crazy-max/ghaction-chocolatey@v1
55+
uses: crazy-max/ghaction-chocolatey@v3
5656
with:
5757
args: install docfx
5858

59-
- name: Build sln
59+
- name: Build TimeWarp.Templates solution
60+
working-directory: TimeWarp.Templates
6061
run: |
6162
dotnet build --configuration Release
6263
6364
- name: DocFX Build
64-
working-directory: Documentation
65+
working-directory: TimeWarp.Templates/Documentation
6566
run: docfx docfx.json
6667
continue-on-error: false
6768

6869
- name: Setup Pages
69-
uses: actions/configure-pages@v2
70+
uses: actions/configure-pages@v5
7071
- name: Upload artifact
7172
uses: actions/upload-pages-artifact@v3
7273
with:
73-
# Upload entire repository
74-
path: './Documentation/_site'
74+
# Upload documentation site
75+
path: './TimeWarp.Templates/Documentation/_site'
7576

7677
- name: Deploy to GitHub Pages
7778
id: deployment
78-
uses: actions/deploy-pages@v1
79+
uses: actions/deploy-pages@v4
7980

8081
- run: echo "🍏 This job's status is ${{ job.status }}."

‎CLAUDE.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Repository Structure
6+
7+
This is a **multi-project repository** containing .NET project templates and supporting infrastructure:
8+
9+
### Main Projects
10+
- **TimeWarp.Architecture/** - Complete distributed microservices architecture template
11+
- **TimeWarp.Console/** - Console application template
12+
- **TimeWarp.Templates/** - Template packaging and documentation
13+
14+
## Development Commands
15+
16+
### TimeWarp.Architecture (Main Template)
17+
Navigate to `TimeWarp.Architecture/` directory first:
18+
19+
**Running Applications:**
20+
- `./Run.ps1` - Runs the Aspire orchestrator (Development environment)
21+
- `./RunDocker.ps1` - Run using Docker containers
22+
- `./RunTailwind.ps1` - Build Tailwind CSS for Web.Spa
23+
24+
**Testing:**
25+
- `./RunTests.ps1` - Runs all test suites using Fixie framework
26+
- `dotnet fixie Tests/[ProjectName]` - Run specific test project
27+
- `dotnet fixie Tests/[ProjectName] --tests [ClassName]` - Run specific test class
28+
- `dotnet fixie Tests/[ProjectName] --tests [ClassName.MethodName]` - Run specific test method
29+
- `dotnet test Tests/EndToEnd.Playwright.Tests` - Run Playwright E2E tests
30+
31+
**Frontend Development (Web.Spa):**
32+
- `npm run css:build` - Build Tailwind CSS
33+
- `npm run tailwind-watch` - Watch and rebuild CSS changes
34+
- `npm run build` - Build TypeScript
35+
- `npm run lint` - Lint TypeScript files
36+
- `npm run prettier` - Format code
37+
38+
### Template Management
39+
- `dotnet new --install TimeWarp.Architecture` - Install the architecture template
40+
- `dotnet new timewarp-architecture -n MyApp` - Create new project from template
41+
42+
## Architecture Overview
43+
44+
### TimeWarp.Architecture Template
45+
A **distributed microservices architecture** demonstrating enterprise .NET patterns:
46+
47+
**Core Technologies:**
48+
- **.NET 9** with C# latest features
49+
- **Blazor WebAssembly/Server** with TimeWarp State management
50+
- **MediatR** for CQRS patterns ("Object In, Object Out")
51+
- **FastEndpoints** for minimal APIs (instead of controllers)
52+
- **Fixie** testing framework (NOT MSTest/xUnit)
53+
- **.NET Aspire** for service orchestration
54+
- **Entity Framework Core** with multiple database providers
55+
- **FluentUI + Tailwind CSS** for styling
56+
57+
**Key Patterns:**
58+
- **Endpoint-Centric Design**: Each API endpoint has dedicated request/response DTOs
59+
- **Mixin System**: Code reuse through `.mixin` files in `Common.Contracts/Mixins/`
60+
- **Source Generation**: Custom Roslyn analyzers create FastEndpoint implementations
61+
- **AssemblyMarker Pattern**: Each assembly has sealed `AssemblyMarker` class
62+
63+
### Container Applications Structure
64+
```
65+
ContainerApps/
66+
├── Web/ # Blazor client + server
67+
├── Api/ # Dedicated API service
68+
├── Grpc/ # gRPC service
69+
├── Aspire/ # Service orchestration
70+
└── Yarp/ # API Gateway/Reverse Proxy
71+
```
72+
73+
## Feature Development Guidelines
74+
75+
### API Contract Structure
76+
- **Location**: `Features/[PluralizedFeatureName]/`
77+
- **Commands**: Write operations (Create, Update, Delete)
78+
- **Queries**: Read operations (prefixed with "Get")
79+
- **Validation**: FluentValidation with shared mixins
80+
81+
### UI Development (FluentUI + Tailwind)
82+
- **Layout**: Use `TimeWarpPage` with FluentUI `Stack`/`Grid`
83+
- **Colors**: FluentUI palette only (automatic light/dark theme support)
84+
- **Tailwind**: Limited to spacing (`m-*`, `p-*`), hover effects, responsiveness
85+
- **Avoid**: Tailwind colors, typography, borders that conflict with FluentUI
86+
87+
## Task Management Workflow
88+
89+
Uses **Kanban folder-based system** in `Kanban/` directory:
90+
91+
### Workflow Structure
92+
- `Backlog/` - Tasks not ready (B### prefix)
93+
- `ToDo/` - Ready tasks (### prefix)
94+
- `InProgress/` - Active development
95+
- `Done/` - Completed tasks
96+
97+
### Definition of Done
98+
**API Endpoints:**
99+
- Server: Endpoint, Handler, Validator, Mapper
100+
- Contracts: Request, Response, RequestValidator
101+
- Integration tests for Handler and Endpoint
102+
103+
**Client Features:**
104+
- State, Actions, Components/Pages
105+
- Integration tests (ShouldClone, ShouldSerialize)
106+
- Action tests and E2E tests
107+
108+
## Testing Framework
109+
110+
**Primary Framework**: Fixie (not MSTest/xUnit)
111+
112+
### Test Organization
113+
```
114+
Tests/
115+
├── Analyzers/ # Source generator tests
116+
├── Common/ # Shared library tests
117+
├── ContainerApps/ # Microservice tests
118+
├── EndToEnd.Playwright.Tests/ # E2E browser tests
119+
├── Libraries/ # Custom library tests
120+
└── Web.*.Integration.Tests/ # Integration tests
121+
```
122+
123+
### Test Commands
124+
- End-to-end tests use `dotnet test` (Playwright)
125+
- All other tests use `dotnet fixie` (Fixie framework)
126+
- Filter by tags: `dotnet fixie -- --Tag Fast --Tag Smoke`
127+
128+
## Important Development Notes
129+
130+
- **Namespace**: All projects use `TimeWarp.Architecture` as root namespace
131+
- **Nullable Reference Types**: Disabled by design choice
132+
- **Generated Code**: Excluded via `Directory.Build.targets`
133+
- **Feature Flags**: Via preprocessor directives (`cosmosdb`, `api`, `grpc`, `web`, `yarp`)
134+
- **State Management**: TimeWarp patterns with Redux DevTools integration
135+
- **Assembly Markers**: Each assembly must contain sealed `AssemblyMarker` class
136+
137+
## Documentation
138+
139+
Comprehensive documentation available in:
140+
- `TimeWarp.Architecture/Documentation/` - Architecture and development guides
141+
- Online docs: https://timewarpengineering.github.io/timewarp-architecture/

0 commit comments

Comments
 (0)