Skip to content

Commit 4391389

Browse files
mythzmythz
committed
Update README.md
1 parent 812cfb2 commit 4391389

File tree

1 file changed

+116
-73
lines changed

1 file changed

+116
-73
lines changed

‎README.md‎

Lines changed: 116 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ Full ASP.NET Core Identity integration with ServiceStack's Auth features:
6161
- **Admin Users UI** - Built-in user management at `/admin-ui/users`
6262
- **API Keys** - Generate and manage API keys for programmatic access
6363

64-
### 📊 AutoQuery CRUD
64+
### 📊 [AutoQuery CRUD](#autoquery-crud-dev-workflow)
6565

6666
Declarative APIs with automatic query and CRUD functionality:
6767

@@ -82,14 +82,15 @@ Modern UI built with:
8282
- **@servicestack/react** - Pre-built form components and AutoQueryGrid
8383
- **SWR** - React Hooks for data fetching with caching
8484

85-
### 🤖 AI Chat Integration
85+
### 🗄️ Database
8686

87-
Built-in AI chat capabilities:
87+
SQLite with dual ORM support:
8888

89-
- **ChatFeature** - Multi-provider AI chat API
90-
- **Configurable Providers** - ServiceStack, OpenAI, Anthropic, Google, Groq, and more
91-
- **Chat History** - Persistent storage with `DbChatStore`
92-
- **Admin Analytics** - Chat usage insights at `/admin-ui/chat`
89+
- **OrmLite** - ServiceStack's fast micro-ORM for services
90+
- **Entity Framework Core** - For Identity and complex queries
91+
- **Code-First Migrations** - EF Core migrations in `/Migrations`
92+
- **Database Admin UI** - Browse data at `/admin-ui/database`
93+
- **SQLite** - Default database - [Upgrade to PostgreSQL/SQL Server/MySQL](#upgrading-to-enterprise-database)
9394

9495
### ⚙️ Background Jobs
9596

@@ -99,6 +100,7 @@ Durable job processing with ServiceStack's Background Jobs:
99100
- **Email Queue** - SMTP email sending via background jobs
100101
- **Recurring Jobs** - Scheduled task execution
101102
- **Job Dashboard** - Monitor jobs at `/admin-ui/jobs`
103+
- Uses monthly rolling Sqlite databases by default - [Upgrade to PostgreSQL/SQL Server/MySQL](#upgrading-to-enterprise-database)
102104

103105
### 📝 MDX Blog
104106

@@ -110,15 +112,6 @@ Integrated markdown blog with:
110112
- **Frontmatter** - YAML metadata for posts
111113
- **Typography Styling** - Beautiful prose with `@tailwindcss/typography`
112114

113-
### 🗄️ Database
114-
115-
SQLite with dual ORM support:
116-
117-
- **OrmLite** - ServiceStack's fast micro-ORM for services
118-
- **Entity Framework Core** - For Identity and complex queries
119-
- **Code-First Migrations** - EF Core migrations in `/Migrations`
120-
- **Database Admin UI** - Browse data at `/admin-ui/database`
121-
122115
### 📡 Request Logging
123116

124117
Comprehensive API logging:
@@ -128,13 +121,6 @@ Comprehensive API logging:
128121
- **Error Tracking** - Automatic error logging
129122
- **Admin Dashboard** - View logs at `/admin-ui/logging`
130123

131-
### 🏥 Health Checks
132-
133-
Production-ready health monitoring:
134-
135-
- **Health Endpoint** - `/up` for load balancer checks
136-
- **Custom Health Checks** - Extensible health check framework
137-
138124
### 🔄 TypeScript DTOs
139125

140126
Automatic TypeScript type generation:
@@ -151,6 +137,22 @@ API documentation with modern tooling:
151137
- **Scalar API Reference** - Interactive API documentation at `/scalar/v1`
152138
- **Development Mode** - API docs available in development
153139

140+
### 🤖 AI Chat Integration
141+
142+
Built-in AI chat capabilities:
143+
144+
- **ChatFeature** - Multi-provider AI chat API
145+
- **Configurable Providers** - ServiceStack, OpenAI, Anthropic, Google, Groq, and more
146+
- **Chat History** - Persistent storage with `DbChatStore`
147+
- **Admin Analytics** - Chat usage insights at `/admin-ui/chat`
148+
149+
### 🏥 Health Checks
150+
151+
Production-ready health monitoring:
152+
153+
- **Health Endpoint** - `/up` for load balancer checks
154+
- **Custom Health Checks** - Extensible health check framework
155+
154156
### 🐳 Docker Deployment
155157

156158
Production-ready containerization:
@@ -274,6 +276,7 @@ npm run test:ui # Run tests with UI
274276
npm run test:run # Run tests once
275277
```
276278

279+
277280
## Configuration
278281

279282
### Key Configuration Files
@@ -354,56 +357,6 @@ npx add-in ef-postgres
354357
npx add-in db-identity
355358
```
356359

357-
## Deployment
358-
359-
### Docker + Kamal
360-
361-
This project includes GitHub Actions for CI/CD with automatic Docker image builds and production [deployment with Kamal](https://docs.servicestack.net/kamal-deploy). The `/config/deploy.yml` configuration is designed to be reusable across projects—it dynamically derives service names, image paths, and volume mounts from environment variables, so you only need to configure your server's IP and hostname using GitHub Action secrets.
362-
363-
### GitHub Action Secrets
364-
365-
**Required - App Specific*:
366-
367-
The only secret needed to be configured per Repository.
368-
369-
| Variable | Example | Description |
370-
|----------|---------|-------------|
371-
| `KAMAL_DEPLOY_HOST` | `example.org` | Hostname used for SSL certificate and Kamal proxy |
372-
373-
**Required** (Organization Secrets):
374-
375-
Other Required variables can be globally configured in your GitHub Organization or User secrets which will
376-
enable deploying all your Repositories to the same server.
377-
378-
| Variable | Example | Description |
379-
|----------|----------|-------------|
380-
| `KAMAL_DEPLOY_IP` | `100.100.100.100` | IP address of the server to deploy to |
381-
| `SSH_PRIVATE_KEY` | `ssh-rsa ...` | SSH private key to access the server |
382-
| `LETSENCRYPT_EMAIL` | `[email protected]` | Email for Let's Encrypt SSL certificate |
383-
384-
**Optional**:
385-
386-
| Variable | Example | Description |
387-
|----------|---------|-------------|
388-
| `SERVICESTACK_LICENSE` | `...` | ServiceStack license key |
389-
390-
**Inferred** (from GitHub Action context):
391-
392-
These are inferred from the GitHub Action context and don't need to be configured.
393-
394-
| Variable | Source | Description |
395-
|----------|--------|-------------|
396-
| `GITHUB_REPOSITORY` | `${{ github.repository }}` | e.g. `acme/example.org` - used for service name and image |
397-
| `KAMAL_REGISTRY_USERNAME` | `${{ github.actor }}` | GitHub username for container registry |
398-
| `KAMAL_REGISTRY_PASSWORD` | `${{ secrets.GITHUB_TOKEN }}` | GitHub token for container registry auth |
399-
400-
#### Features
401-
402-
- **Docker containerization** with optimized .NET images
403-
- **SSL auto-certification** via Let's Encrypt
404-
- **GitHub Container Registry** integration
405-
- **Volume persistence** for App_Data including any SQLite database
406-
407360
## AutoQuery CRUD Dev Workflow
408361

409362
For Rapid Development simple [TypeScript Data Models](https://docs.servicestack.net/autoquery/okai-models) can be used to generate C# AutoQuery APIs and DB Migrations.
@@ -471,6 +424,96 @@ Which will drop the table and then you can get rid of the AutoQuery APIs, DB Mig
471424
npx okai rm Transaction.d.ts
472425
```
473426

427+
## Deployment
428+
429+
### Docker + Kamal
430+
431+
This project includes GitHub Actions for CI/CD with automatic Docker image builds and production [deployment with Kamal](https://docs.servicestack.net/kamal-deploy). The `/config/deploy.yml` configuration is designed to be reusable across projects—it dynamically derives service names, image paths, and volume mounts from environment variables, so you only need to configure your server's IP and hostname using GitHub Action secrets.
432+
433+
### GitHub Action Secrets
434+
435+
**Required - App Specific*:
436+
437+
The only secret needed to be configured per Repository.
438+
439+
| Variable | Example | Description |
440+
|----------|---------|-------------|
441+
| `KAMAL_DEPLOY_HOST` | `example.org` | Hostname used for SSL certificate and Kamal proxy |
442+
443+
**Required** (Organization Secrets):
444+
445+
Other Required variables can be globally configured in your GitHub Organization or User secrets which will
446+
enable deploying all your Repositories to the same server.
447+
448+
| Variable | Example | Description |
449+
|----------|----------|-------------|
450+
| `KAMAL_DEPLOY_IP` | `100.100.100.100` | IP address of the server to deploy to |
451+
| `SSH_PRIVATE_KEY` | `ssh-rsa ...` | SSH private key to access the server |
452+
| `LETSENCRYPT_EMAIL` | `[email protected]` | Email for Let's Encrypt SSL certificate |
453+
454+
**Optional**:
455+
456+
| Variable | Example | Description |
457+
|----------|---------|-------------|
458+
| `SERVICESTACK_LICENSE` | `...` | ServiceStack license key |
459+
460+
**Inferred** (from GitHub Action context):
461+
462+
These are inferred from the GitHub Action context and don't need to be configured.
463+
464+
| Variable | Source | Description |
465+
|----------|--------|-------------|
466+
| `GITHUB_REPOSITORY` | `${{ github.repository }}` | e.g. `acme/example.org` - used for service name and image |
467+
| `KAMAL_REGISTRY_USERNAME` | `${{ github.actor }}` | GitHub username for container registry |
468+
| `KAMAL_REGISTRY_PASSWORD` | `${{ secrets.GITHUB_TOKEN }}` | GitHub token for container registry auth |
469+
470+
#### Features
471+
472+
- **Docker containerization** with optimized .NET images
473+
- **SSL auto-certification** via Let's Encrypt
474+
- **GitHub Container Registry** integration
475+
- **Volume persistence** for App_Data including any SQLite database
476+
477+
## AI-Assisted Development with CLAUDE.md
478+
479+
As part of our objectives of improving developer experience and embracing modern AI-assisted development workflows - all new .NET SPA templates include a comprehensive `AGENTS.md` file designed to optimize AI-assisted development workflows.
480+
481+
### What is CLAUDE.md?
482+
483+
`CLAUDE.md` and [AGENTS.md](https://agents.md) onboards Claude (and other AI assistants) to your codebase by using a structured documentation file that provides it with complete context about your project's architecture, conventions, and technology choices. This enables more accurate code generation, better suggestions, and faster problem-solving.
484+
485+
### What's Included
486+
487+
Each template's `AGENTS.md` contains:
488+
489+
- **Project Architecture Overview** - Technology stack, design patterns, and key architectural decisions
490+
- **Project Structure** - Gives Claude a map of the codebase
491+
- **ServiceStack Conventions** - DTO patterns, Service implementation, AutoQuery, Authentication, and Validation
492+
- **API Integration** - TypeScript DTO generation, API client usage, component patterns, and form handling
493+
- **Database Patterns** - OrmLite setup, migrations, and data access patterns
494+
- **Common Development Tasks** - Step-by-step guides for adding APIs, implementing features, and extending functionality
495+
- **Testing & Deployment** - Test patterns and deployment workflows
496+
497+
### Extending with Project-Specific Details
498+
499+
The existing `CLAUDE.md` serves as a solid foundation, but for best results, you should extend it with project-specific details like the purpose of the project, key parts and features of the project and any unique conventions you've adopted.
500+
501+
### Benefits
502+
503+
- **Faster Onboarding** - New developers (and AI assistants) understand project conventions immediately
504+
- **Consistent Code Generation** - AI tools generate code following your project's patterns
505+
- **Better Context** - AI assistants can reference specific ServiceStack patterns and conventions
506+
- **Reduced Errors** - Clear documentation of framework-specific conventions
507+
- **Living Documentation** - Keep it updated as your project evolves
508+
509+
### How to Use
510+
511+
Claude Code and most AI Assistants already support automatically referencing `CLAUDE.md` and `AGENTS.md` files, for others you can just include it in your prompt context when asking for help, e.g:
512+
513+
> Using my project's AGENTS.md, can you help me add a new AutoQuery API for managing Products?
514+
515+
The AI will understand your App's ServiceStack conventions, React setup, and project structure, providing more accurate and contextual assistance.
516+
474517
## Learn More
475518

476519
- [react-templates.net](https://react-templates.net)

0 commit comments

Comments
 (0)