faysilalshareef/readme-gen

README Generation — Project Analysis

Core Principles

• README is generated from project analysis, not written from scratch
• Includes badges, setup instructions, architecture overview, and API summary
• Microservice mode: per-repo README + umbrella README
• Generic mode: single comprehensive README
• Detect existing README and merge/update rather than overwrite

Key Patterns

Per-Service README Template

# {Company}.{Domain}.{Side}

{Brief description of what this service does}

## Badges
![Build](https://github.com/{company}/{repo}/actions/workflows/build.yml/badge.svg)
![.NET](https://img.shields.io/badge/.NET-{version}-purple)

## Overview
{One-paragraph description of the service purpose and role in the system}

## Architecture
This is the **{side}** service in the {Domain} microservice system.

```mermaid
graph LR
    GW[Gateway] -->|gRPC| THIS[This Service]
    THIS -->|Events| SB[Service Bus]
    THIS -->|SQL| DB[(Database)]

Prerequisites

• .NET SDK {version}
• Docker (for local infrastructure)
• Azure CLI (for deployment)

Getting Started

Local Development

# Clone
git clone {repo-url}
cd {repo-name}

# Restore and build
dotnet restore
dotnet build

# Run (requires local SQL Server)
dotnet run --project src/{Company}.{Domain}.{Side}

With .NET Aspire

cd {domain}-apphost
dotnet run

Project Structure

src/
  {Company}.{Domain}.{Side}/         # Main application
  {Company}.{Domain}.{Side}.Domain/  # Domain entities
  {Company}.{Domain}.{Side}.Application/ # Handlers, queries
  {Company}.{Domain}.{Side}.Infrastructure/ # DB, Service Bus
tests/
  {Company}.{Domain}.{Side}.Tests/   # Unit + integration tests

API / Events

Events Produced (Command Side)

| Event | Description | |---|---| | OrderCreated | New order created | | OrderUpdated | Order details changed |

gRPC Services (Query Side)

| Service | RPC | Description | |---|---|---| | OrderQueries | GetOrder | Get order by ID | | OrderQueries | GetOrders | List with pagination |

Configuration

Key configuration in appsettings.json: | Key | Description | Required | |---|---|---| | ConnectionStrings:DefaultConnection | SQL Server | Yes | | ServiceBus:ConnectionString | Azure Service Bus | Yes | | ExternalServices:QueryServiceUrl | Query service URL | Yes |

Testing

dotnet test                    # All tests
dotnet test --filter Unit      # Unit tests only
dotnet test --filter Integration # Integration tests only

Deployment

See Deployment Runbook for detailed instructions.

### Umbrella README (Multi-Service)

```markdown
# {Company} {Domain} Platform

## System Overview
{Domain} is a microservice platform using CQRS + Event Sourcing.

## Services
| Service | Repository | Purpose |
|---|---|---|
| Command | [{domain}-command]({url}) | Event sourcing, business logic |
| Query | [{domain}-query]({url}) | Read projections (SQL) |
| Cosmos Query | [{domain}-cosmos-query]({url}) | Read projections (Cosmos) |
| Processor | [{domain}-processor]({url}) | Event routing |
| Gateway | [{domain}-gateway]({url}) | REST API |
| Control Panel | [{domain}-controlpanel]({url}) | Admin UI |

## Architecture
```mermaid
graph LR
    CP[Control Panel] -->|REST| GW[Gateway]
    GW -->|gRPC| CMD[Command]
    GW -->|gRPC| QRY[Query]
    CMD -->|Events| SB[Service Bus]
    SB --> QRY
    SB --> PROC[Processor]

Quick Start

See Onboarding Guide for complete setup.

Documentation

• Architecture
• ADRs
• Deployment Runbook

### Analysis for README Generation

```bash
# Detect project type
find . -name "*.csproj" | head -5

# Get .NET version
grep "TargetFramework" Directory.Build.props 2>/dev/null || \
  grep "TargetFramework" src/*/*.csproj | head -1

# Find main entry point
find . -name "Program.cs" -path "*/src/*" | head -3

# Find gRPC services
grep -r "MapGrpcService\|MapScalarApiReference" --include="*.cs" src/

# Find tests
find . -name "*Tests*" -type d | head -5

Anti-Patterns

| Anti-Pattern | Correct Approach | |---|---| | Manually written README that goes stale | Generate from project analysis | | Missing setup instructions | Always include prerequisites and steps | | No architecture overview | Include Mermaid diagram | | Copy-paste from other projects | Analyze this specific project | | README without badges | Add build status and .NET version badges |

Detect Existing Patterns

# Find existing README
find . -name "README.md" -maxdepth 2

# Check README content
head -20 README.md 2>/dev/null

# Find documentation directory
ls docs/ 2>/dev/null

Adding to Existing Project

1. Read existing README before generating — preserve custom sections
2. Update outdated sections rather than full rewrite
3. Add missing sections (badges, architecture, setup)
4. Verify all commands in setup instructions actually work
5. Keep README concise — link to detailed docs instead of embedding