Projects.md

Projects

This document describes each project in the OpenCashFlow solution, their responsibilities, and how they interact.

Solution Overview

OpenCashFlow.sln
├── src/
│   ├── OpenCashFlow.App/          # Web application (MVC)
│   ├── OpenCashFlow.API/          # REST API
│   ├── OpenCashFlow.Admin/        # Admin panel
│   └── OpenCashFlow.Shared/       # Shared library
└── tests/
    └── OpenCashFlow.Test/         # Test project

OpenCashFlow.App

Type: ASP.NET Core MVC Web Application Port: 7001 (HTTPS) Purpose: User-facing web interface

Responsibilities

• Render Razor views with Tabler UI
• Handle user authentication flows (login, register, password reset)
• Serve static assets (CSS, JavaScript, images)
• Make AJAX calls to the API for data operations
• Manage user sessions via cookies

Key Directories

OpenCashFlow.App/
├── Controllers/           # MVC controllers
│   ├── HomeController.cs         # Authentication pages
│   ├── PaymentController.cs      # Payment views
│   ├── CompanyController.cs      # Company management
│   └── BillingController.cs      # Subscription UI
├── Views/                 # Razor views
│   ├── Shared/
│   │   ├── _Layout.cshtml        # Master layout
│   │   └── _LoginLayout.cshtml   # Auth pages layout
│   ├── Home/                     # Auth views
│   ├── Payment/                  # Payment views
│   └── _Partials/                # Reusable components
├── ViewModels/            # View-specific models
├── ViewComponents/        # Reusable view components
├── wwwroot/               # Static files
│   ├── css/                      # Custom styles
│   ├── js/                       # Custom JavaScript
│   ├── libs/                     # Third-party libraries
│   └── vendor/tabler/            # Tabler framework
├── AppStart/              # Startup configuration
└── Program.cs             # Application entry point

Configuration

{
  "Account": {
    "CookieDomain": ".opencashflow.local",
    "API": "https://api.opencashflow.local",
    "AppUrl": "https://app.opencashflow.local/"
  }
}

Dependencies

• References OpenCashFlow.Shared
• Communicates with OpenCashFlow.API via HTTP

---

OpenCashFlow.API

Type: ASP.NET Core Web API Port: 7002 (HTTPS) Purpose: RESTful backend services

Responsibilities

• Expose REST endpoints for all data operations
• Handle JWT authentication and authorization
• Process Stripe webhooks
• Implement business logic via services
• Validate incoming requests

Key Directories

OpenCashFlow.API/
├── Controllers/           # API controllers
│   ├── v1/
│   │   ├── AuthenticationController.cs
│   │   ├── PaymentController.cs
│   │   ├── CompanyController.cs
│   │   ├── EmployeeController.cs
│   │   └── BillingController.cs
├── AppStart/              # Startup configuration
│   ├── 00_Logging.cs
│   ├── 01_Configuration.cs
│   ├── 02_Services.cs
│   └── 03_Authentication.cs
├── Middlewares/           # Custom middleware
│   └── SubscriptionAuthorizationMiddleware.cs
├── Filters/               # Action filters
└── Program.cs             # Application entry point

API Versioning

Routes follow the pattern: v{version:apiVersion}/[controller]

[ApiController]
[ApiVersion("1.0")]
[Route("v{version:apiVersion}/[controller]")]
public class PaymentController : ControllerBase
{
    [HttpGet]
    public async Task<IActionResult> GetAll() { }

    [HttpGet("{id}")]
    public async Task<IActionResult> GetById(Guid id) { }

    [HttpPost]
    public async Task<IActionResult> Create([FromBody] Payment_Create_DTO dto) { }
}

Authentication Flow

1. User submits credentials to /v1/Authentication/login
2. API validates credentials and generates JWT token
3. Token is returned and stored in HTTP-only cookie
4. Subsequent requests include the cookie automatically
5. API validates token on each request

Key Endpoints

Endpoint	Method	Description
/v1/Authentication/login	POST	User login
/v1/Authentication/register	POST	User registration
/v1/Authentication/refresh-token	POST	Refresh JWT token
/v1/Payment	GET	List payments
/v1/Payment/{id}	GET	Get payment by ID
/v1/Payment	POST	Create payment
/v1/Payment/{id}	PUT	Update payment
/v1/Payment/{id}	DELETE	Soft delete payment
/v1/Company	GET/POST/PUT	Company CRUD
/v1/Billing/webhook	POST	Stripe webhook handler

---

OpenCashFlow.Admin

Type: ASP.NET Core MVC Web Application Port: 7003 (HTTPS) Purpose: System administration

Responsibilities

• Manage system-wide settings
• View audit logs across all tenants
• Monitor system health
• Manage plans and subscriptions
• User administration

Key Features

• Cross-tenant data access (admin only)
• Audit log viewer
• Subscription management
• System configuration

Access Control

Admin users require the GIManagers role, which is a hidden system role not assignable through normal UI.

---

OpenCashFlow.Shared

Type: .NET Class Library Purpose: Shared code across all projects

Responsibilities

• Define database entities (models)
• Provide DTOs for API contracts
• Implement services and repositories
• Configure Entity Framework Core
• Define enumerations and constants
• Provide AutoMapper profiles

Key Directories

OpenCashFlow.Shared/
├── Data/
│   ├── ApplicationDbContext.cs   # EF Core DbContext
│   ├── Migrations/               # Database migrations
│   └── Seeding/                  # Seed data
├── Models/                # Entity definitions
│   ├── Payment.cs
│   ├── Company.cs
│   ├── AspNetUser.cs
│   └── ...
├── DTOs/                  # Data Transfer Objects
│   ├── Payment_Create_DTO.cs
│   ├── Payment_List_DTO.cs
│   └── ...
├── Services/              # Business logic
│   ├── Interfaces/
│   ├── PaymentService.cs
│   ├── CompanyService.cs
│   └── EmailService.cs
├── Repositories/          # Data access
│   ├── Interfaces/
│   ├── PaymentRepository.cs
│   └── CompanyRepository.cs
├── Enums/                 # Enumerations
│   ├── Permissions.cs
│   ├── GenderTypes.cs
│   └── EntryTypes.cs
├── Mappings/              # AutoMapper profiles
│   └── MappingProfile.cs
└── Helpers/               # Utility classes
    ├── Configuration.cs
    └── JwtHelper.cs

DbContext Definition

public class ApplicationDbContext : DbContext
{
    // Identity
    public DbSet<AspNetUser> AspNetUser_DS { get; set; }
    public DbSet<AspNetRole> AspNetRole_DS { get; set; }
    public DbSet<AspNetUserRole> AspNetUserRole_DS { get; set; }

    // Business entities
    public DbSet<Company> Company_DS { get; set; }
    public DbSet<Payment> Payment_DS { get; set; }
    public DbSet<Payment_Method_LookUps> Payment_Method_LookUps_DS { get; set; }

    // Billing
    public DbSet<Plan> Plan_DS { get; set; }
    public DbSet<Company_Subscription> Company_Subscription_DS { get; set; }

    // Admin
    public DbSet<Admin_AuditLog> Admin_AuditLog_DS { get; set; }
}

Entity Example

public class Payment
{
    public Guid PaymentID { get; set; }
    public Guid TenantID { get; set; }
    public Guid? RequestId { get; set; }  // Idempotency key

    public decimal Amount { get; set; }
    public string EntryType { get; set; }  // Income/Outcome
    public string? Description { get; set; }

    public int PaymentMethodID { get; set; }
    public int DocumentTypeID { get; set; }
    public Guid UserID { get; set; }

    // Audit fields
    public string CreatedBy { get; set; }
    public DateTime DateIns { get; set; }
    public string? EditedBy { get; set; }
    public DateTime? DateEdit { get; set; }
    public bool IsDeleted { get; set; }
}

DTO Example

public class Payment_Create_DTO
{
    [Required]
    public decimal Amount { get; set; }

    [Required]
    public string EntryType { get; set; }

    public string? Description { get; set; }

    [Required]
    public int PaymentMethodID { get; set; }

    [Required]
    public int DocumentTypeID { get; set; }
}

public class Payment_List_DTO
{
    public Guid PaymentID { get; set; }
    public decimal Amount { get; set; }
    public string EntryType { get; set; }
    public string? Description { get; set; }
    public string PaymentMethodName { get; set; }
    public DateTime CreatedAt { get; set; }
}

---

OpenCashFlow.Test

Type: xUnit Test Project Purpose: Automated testing

Test Categories

• Unit Tests - Test individual services and helpers
• Integration Tests - Test API endpoints with test database
• Repository Tests - Test data access layer

Directory Structure

OpenCashFlow.Test/
├── Unit/
│   ├── Services/
│   └── Helpers/
├── Integration/
│   ├── API/
│   └── Repositories/
├── Fixtures/              # Test data and setup
├── Helpers/               # Test utilities
└── appsettings.Test.json  # Test configuration

Running Tests

# Run all tests
dotnet test

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

# Run specific category
dotnet test --filter "Category=Unit"

---

Project Dependencies

OpenCashFlow.App
    └── OpenCashFlow.Shared
    └── HTTP → OpenCashFlow.API

OpenCashFlow.API
    └── OpenCashFlow.Shared

OpenCashFlow.Admin
    └── OpenCashFlow.Shared

OpenCashFlow.Test
    └── OpenCashFlow.Shared
    └── OpenCashFlow.API (for integration tests)

NuGet Packages

Common Packages (Shared)

Package	Purpose
Microsoft.EntityFrameworkCore	ORM
Npgsql.EntityFrameworkCore.PostgreSQL	PostgreSQL provider
AutoMapper	Object-object mapping
FluentValidation	Input validation

API-Specific Packages

Package	Purpose
Microsoft.AspNetCore.Authentication.JwtBearer	JWT authentication
Asp.Versioning.Mvc	API versioning
Swashbuckle.AspNetCore	Swagger/OpenAPI
Stripe.net	Stripe integration

App-Specific Packages

Package	Purpose
Microsoft.AspNetCore.SignalR	Real-time communication
Polly	Retry policies