Welcome Developer›Backend›Getting Started

01 - Getting Started

Clone, restore, migrate, run. By the end of this page you'll have the backend running on http://localhost:5000 with Swagger, Hangfire dashboard, and an empty PostgreSQL database ready to accept requests from the Flutter app.

Prerequisites

ToolVersionWhy
.NET SDK8.0+ASP.NET Core runtime and build toolchain
PostgreSQL14+Primary database (snake_case via EF Core naming conventions)
Visual Studio 2022 / RiderLatestRecommended IDE with C# debugger (VS Code also works)
Postman / InsomniaAnyOptional - for hitting endpoints directly
BashVerify .NET installation 
dotnet --version
# Should show 8.0.x or higher

dotnet --list-sdks
# Expected: 8.0.xxx [C:\Program Files\dotnet\sdk]

Step 1 - Clone & Restore

BashClone and restore NuGet packages 
git clone <repo-url> D:\MO_Project\ekyc
cd D:\MO_Project\ekyc\backend
dotnet restore MO.Ekyc.sln

Step 2 - Set up PostgreSQL

Create a database named ekyc3 and a schema named ekyc. Default credentials are postgres/root123 (change in appsettings.Development.json if yours differ).

SQLDatabase + schema 
CREATE DATABASE ekyc3;
-- Connect to ekyc3
CREATE SCHEMA ekyc;
No migration files

The project currently has no EF Core migration files. The schema is managed via EntityTypeConfiguration classes applied in OnModelCreating. Use one of these approaches for initial setup:

  • Run a one-time dbContext.Database.EnsureCreatedAsync() from a dev controller (DevController has purge endpoints)
  • Check DB Actions Checklist for the full schema setup steps
  • Run DDL scripts from the backend/database/ folder if present

Step 3 - Configure appsettings

Development settings live in backend/src/MO.Ekyc.Api/appsettings.Development.json. The defaults should work for local PostgreSQL with mock mode enabled.

backend/src/MO.Ekyc.Api/appsettings.Development.jsonJSON 
{
  "ConnectionStrings": {
    "EkycDb": "Host=127.0.0.1;Port=5432;Database=ekyc3;Username=postgres;Password=root123;Search Path=ekyc"
  },
  "MockMode": {
    "GlobalMockEnabled": true
  },
  "Sms": { "Mode": "FIXED_OTP", "FixedOtp": "1234" },
  "Email": { "Mode": "FIXED_OTP", "FixedOtp": "1234" }
}
Mock mode is on by default

With GlobalMockEnabled: true, the backend skips all real external provider calls. OTPs are fixed to 1234. You can run the full Flutter journey without hitting NSDL, Decentro, Razorpay, or any other production provider. See 02 - Mock Mode.

Step 4 - Run the API

Bashdotnet run 
cd D:\MO_Project\ekyc\backend\src\MO.Ekyc.Api
dotnet run

# Output:
# Now listening on: http://localhost:5000
# Application started. Press Ctrl+C to shut down.

Step 5 - Verify the Setup

URLPurpose
http://localhost:5000/swaggerInteractive API explorer. Try any endpoint from the browser.
http://localhost:5000/hangfireBackground job dashboard. Shows queued / processing / failed jobs.
http://localhost:5000/api/v1/journey/initSmoke test - should return a new session with JSON body.
BashQuick smoke test with curl 
curl "http://localhost:5000/api/v1/journey/init?device_type=DESKTOP"

# Expected: 200 OK with { "success": true, "data": { "leadSessionId": "...", ... } }

Step 6 - Connect the Flutter App

The Flutter app defaults to http://localhost:5000 in dev mode. Just start it up and it should talk to your local backend.

BashStart Flutter client 
cd D:\MO_Project\ekyc\flutter_app
C:\flutter\bin\flutter run -d chrome --web-port 8080

Open http://localhost:8080 in Chrome. You should see Stage 0 loader, then navigate to Stage 1 Registration.

CORS

The backend's CORS policy (backend/src/MO.Ekyc.Api/appsettings.json → Cors.AllowedOrigins) already permits http://localhost:3000 (WarRoom) and http://localhost:8080 (Flutter web). Add more origins if you run on other ports.

Troubleshooting

"Cannot connect to PostgreSQL"

"Schema 'ekyc' does not exist"

"Port 5000 already in use"

"Hangfire dashboard returns 401"