Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/mgnischor/docflow-backend

DocFlow.Backend is an ASP.NET Core API for enterprise process knowledge management. Its purpose is to help organizations capture, structure, govern, search, and evolve business process knowledge across teams, business units, and workspaces.
https://github.com/mgnischor/docflow-backend

api csharp docker document-management dotnet enterprise entity-framework-core kubernetes postgresql

Last synced: 3 months ago
JSON representation

DocFlow.Backend is an ASP.NET Core API for enterprise process knowledge management. Its purpose is to help organizations capture, structure, govern, search, and evolve business process knowledge across teams, business units, and workspaces.

Awesome Lists containing this project

README 

          
# DocFlow.Backend



DocFlow.Backend is an ASP.NET Core API for enterprise process knowledge management.

Its purpose is to help organizations capture, structure, govern, search, and evolve business process knowledge across teams, business units, and workspaces.



The platform is intended to support the full lifecycle of process knowledge, including process modeling, versioning, linked knowledge assets, review and approval workflows, search, traceability, and audit history.



[![release-pipeline](https://github.com/mgnischor/docflow-backend/actions/workflows/build.yml/badge.svg)](https://github.com/mgnischor/docflow-backend/actions/workflows/build.yml)



## Current Repository Status



This repository is currently in an early bootstrap stage.

At the moment it contains a minimal .NET 10 ASP.NET Core application with controllers and OpenAPI enabled, and it should be treated as the starting point for a larger production-grade backend rather than as a finished architecture.



The first authentication slice is now available with JWT bearer token issuance, refresh-token rotation, current-user introspection, and logout token revocation endpoints.

An Entity Framework Core persistence foundation backed by PostgreSQL is now wired into the application, and refresh tokens are stored in the database instead of process memory.

The HTTP platform foundation now includes URL-segment API versioning, correlation-aware request logging and exception handling, and versioned health endpoints with database readiness checks.



## Product Scope



The backend is being designed to support the following business capabilities:



- Multi-tenant organizations, business units, and workspaces

- Users, roles, permissions, memberships, and policy-based access control

- Process catalogs, categories, tags, and ownership metadata

- Process definitions with lifecycle states such as Draft, InReview, Approved, Rejected, and Archived

- Versioned process content with steps, inputs, outputs, controls, risks, systems, KPIs, and SLAs

- Linked knowledge assets such as SOPs, manuals, policies, templates, checklists, external links, and uploaded files

- Review and approval workflows, comments, assignments, notifications, and reminders

- Audit trails, change history, and traceability across process and document updates

- Search, filtering, pagination, sorting, and reporting-friendly query endpoints



## Target Technical Stack



The project is intended to standardize on the following technical stack:



- C# as the implementation language

- .NET 10 or higher, using the highest stable SDK and runtime compatible with the solution

- ASP.NET Core for the HTTP API

- Entity Framework Core as the ORM and persistence technology

- PostgreSQL with Npgsql as the relational database provider

- Scalar with Scalar.AspNetCore for API documentation generation and presentation

- xUnit as the only automated test framework

- Docker and Kubernetes compatibility for containerized execution



## Architecture Direction



The backend should follow Domain-Driven Design throughout the codebase, not only in concepts but also in directory structure, file organization, namespaces, and project boundaries.



A practical target structure is:



- Domain: entities, aggregates, value objects, enums, domain services, invariants

- Application: commands, queries, DTOs, validators, orchestration logic

- Infrastructure: EF Core persistence, authentication, storage, search, notifications, integrations

- API: controllers, request and response contracts, middleware, filters, documentation configuration



Core architectural principles:



- Keep public HTTP APIs controller-based

- Keep business rules out of controllers and persistence configuration classes

- Keep EF Core entities and persistence concerns out of public transport contracts

- Prefer modular and layered boundaries with high feature cohesion

- Avoid unnecessary complexity unless the business requirement clearly justifies it



## API Conventions



The API is intended to follow these conventions:



- All endpoints use URL path versioning with the `/api/{version}/` prefix

- The `/api/{version}/docs` route is reserved for API documentation

- Input validation must be explicit and consistent

- Errors should be returned using ProblemDetails

- List endpoints should support pagination, filtering, and sorting

- Public contracts must be explicit rather than exposing persistence models directly



Representative endpoint families include:



- `/api/{version}/auth`

- `/api/{version}/tenants`

- `/api/{version}/users`

- `/api/{version}/roles`

- `/api/{version}/process-catalogs`

- `/api/{version}/processes`

- `/api/{version}/processes/{id}/versions`

- `/api/{version}/processes/{id}/steps`

- `/api/{version}/knowledge-assets`

- `/api/{version}/attachments`

- `/api/{version}/reviews`

- `/api/{version}/approvals`

- `/api/{version}/search`

- `/api/{version}/audit-logs`

- `/api/{version}/docs`



## Security and Quality Baseline



Security and delivery expectations for this backend include:



- Early adoption of authentication and authorization

- JWT bearer authentication for API consumers

- Strict tenant isolation in queries and mutations

- Policy-based authorization for privileged operations

- Security decisions aligned with MITRE ATT&CK and OWASP guidance, including the OWASP Top 10 and OWASP API Security Top 10

- SHA3-256 as the default API hashing algorithm

- ChaCha20-Poly1305 as the default API encryption algorithm

- UTC timestamps, audit metadata, and traceability for business-relevant changes

- XML documentation comments across C# code, written in English and descriptive enough to explain intent, parameters, return values, and important behavior



## Persistence and Operations



The production-oriented persistence and runtime expectations are:



- EF Core migrations for schema changes

- EF Core migration source files kept under `Source/Infrastructure/Persistence/Migrations`

- Companion SQL artifacts for migrations kept under `Source/Infrastructure/Persistence/Migrations/SQL`

- Explicit relationships, indexes, uniqueness constraints, and concurrency handling where required

- Environment-driven configuration

- Support for local execution and containerized execution without code changes

- Container-friendly behavior, including health endpoints and predictable startup and shutdown behavior

- Replaceable abstractions for storage, search, and external notifications



Current operational endpoints and diagnostics:



- Liveness probe: `/api/v1/health/live`

- Readiness probe: `/api/v1/health/ready`

- Supported API versions are reported in the `api-supported-versions` response header

- The API accepts and echoes `X-Correlation-ID`, and error responses include the same value as the `correlationId` ProblemDetails extension



## Development and Testing Expectations



The project is expected to include:



- Unit tests for domain rules, validators, and critical services

- Integration tests for controllers, persistence, authorization, and main workflows

- Coverage for process lifecycle, approvals, tenant isolation, and search behavior

- README updates when major project changes affect setup, architecture, runtime behavior, operations, or project-wide usage



## Formatting



The official formatter for C# source files in this repository is CSharpier.



Formatting behavior must follow the configuration stored in the root-level `.prettierrc`, `.editorconfig`, and `.csharpierrc` files.

Those files are the single source of truth for formatting decisions across the project.



At the end of every code change, run the formatting script below before considering the work complete:



```powershell

.\Scripts\FormatSourceFiles.ps1

```



If you need to validate formatting without rewriting files, use:



```powershell

.\Scripts\FormatSourceFiles.ps1 -Verify

```



## Running the Current Bootstrap



Prerequisites:



- .NET 10 SDK or a higher compatible stable SDK installed locally

- PostgreSQL available locally or through a reachable environment-specific connection string



Configuration:



- The primary database connection string key is `ConnectionStrings:DocFlowDatabase`

- For local development, `appsettings.Development.json` provides a PostgreSQL default pointing to `localhost:5432`

- For other environments, override the connection string with environment configuration such as `ConnectionStrings__DocFlowDatabase`



Common commands:



```bash

dotnet restore

dotnet build

dotnet ef database update --project DocFlow.Backend.csproj

dotnet run --project DocFlow.Backend.csproj

```



## CI/CD



The repository now uses a three-stage GitHub Actions release pipeline that runs only when a commit is pushed to the `release` branch.



Execution order:



- `build.yml`: restores, builds, versions, publishes, and packages the API binary.

- `test.yml`: runs after `build.yml`, verifies formatting, validates migration SQL companions, and executes the automated test suite.

- `release.yml`: runs after `test.yml`, creates the Git tag for the computed version, and publishes the packaged binary as a GitHub Release asset.



Versioning strategy:



- The release version uses the format `major.minor.build`.

- `major` comes from the optional GitHub Actions repository variable `VERSION_MAJOR` and defaults to `1`.

- `minor` comes from the optional GitHub Actions repository variable `VERSION_MINOR` and defaults to `0`.

- `build` is auto-incremented from the GitHub Actions `run_number` of the `build.yml` workflow.



Migration policy enforced by CI:



- Every EF Core migration source file must exist in `Source/Infrastructure/Persistence/Migrations`.

- Every EF Core migration must also have a companion SQL file in `Source/Infrastructure/Persistence/Migrations/SQL`.



The current bootstrap enables controllers and built-in OpenAPI support during development.

As the project evolves, the documentation experience is expected to move to Scalar under the reserved `/api/{version}/docs` route.



During development, the OpenAPI document is currently available at `/api/v1/openapi/v1.json`.



## Authentication Bootstrap



The API now exposes the first authentication endpoints under `/api/v1/auth`:



- `POST /api/v1/auth/login`

- `POST /api/v1/auth/refresh`

- `GET /api/v1/auth/me`

- `POST /api/v1/auth/logout`



JWT settings are configured under `Authentication:Jwt` and bootstrap development users are configured under `Authentication:BootstrapUsers`.



The default development profile currently seeds one bootstrap user in `appsettings.Development.json`:



- Email: `admin@docflow.local`

- Password: `ChangeMe123!`

- Role: `PlatformAdministrator`



This bootstrap identity flow is intended only for the current foundation phase.

Refresh tokens are stored as SHA3-256 hashed values in the PostgreSQL database, so the authentication slice now depends on the persistence foundation being configured and migrated.



To validate the authentication slice locally, run:



```bash

dotnet test tests/DocFlow.Backend.Tests/DocFlow.Backend.Tests.csproj --filter AuthenticationEndpointsTests

dotnet test tests/DocFlow.Backend.Tests/DocFlow.Backend.Tests.csproj --filter RefreshTokenPersistenceTests

```



## Near-Term Roadmap



The expected implementation path for the repository is:



1. Establish project structure, configuration, persistence setup, and authentication foundations.

2. Implement tenants, users, roles, and access-control foundations.

3. Build process catalogs, process definitions, process versions, and process steps.

4. Add knowledge assets, attachments, reviews, approvals, and audit workflows.

5. Expand search, operational hardening, documentation, and automated test coverage.