Skip to content

Quick Start

This guide walks through creating your first tenant, user, borrower, and loan. It assumes you've completed the Installation steps.

1. Create a Tenant

Tenants are created programmatically. Use the Django shell:

cd backend
uv run python manage.py shell

from apps.tenants.models import Tenant, Domain

# Create a tenant
tenant = Tenant.objects.create(
    name="Acme Lending",
    slug="acme",
    status="active",
    locale="en-US",
    timezone="America/New_York",
    default_currency="USD",
)

# Map a domain to the tenant
Domain.objects.create(
    tenant=tenant,
    domain="acme.localhost",
    is_primary=True,
)

This creates the tenant_acme PostgreSQL schema and runs all migrations in it.

2. Create an Admin User

Switch to the tenant schema and create a user:

from django_pgschemas.schema import Schema

with Schema.create(schema_name="tenant_acme"):
    from apps.users.models import User

    user = User.objects.create_user(
        email="admin@acme.com",
        password="changeme123",
        first_name="Admin",
        last_name="User",
        tenant_role="superadmin",
    )

3. Start the Services

Open separate terminals for each service:

cd backend
uv run python manage.py runserver

cd frontend/admin
npm run dev

cd backend
uv run celery -A config worker -l info

4. Log In to the Admin Dashboard

  1. Open http://localhost:5173 in your browser
  2. Log in with admin@acme.com / changeme123
  3. You should see the dashboard with empty stats

5. Create a Lending Program

Before creating loans, you need a lending program and product:

  1. Navigate to Administration > Programs in the sidebar
  2. Click Create
  3. Fill in:
    • Name: "Consumer Installment"
    • Program Type: Installment Loan
    • Day Count Convention: Actual/365
    • Accrual Method: Simple
    • Payment Allocation Order: ["interest", "fees", "principal"]
  4. Save

6. Create a Loan Product

  1. Navigate to Administration > Products
  2. Click Create
  3. Fill in:
    • Name: "36-Month Fixed Personal Loan"
    • Program: Select "Consumer Installment"
    • Rate Type: Fixed
    • Default Interest Rate: 0.085 (8.5%)
    • Min Term: 12
    • Max Term: 60
    • Min Amount: 1000
    • Max Amount: 50000
    • Grace Period: 15 days
  4. Save

7. Create a Borrower

  1. Navigate to Origination > Borrowers
  2. Click Create
  3. Fill in name, SSN last four, and other required fields
  4. Save
  5. Add an address, email, and phone via the tabs on the borrower's show page

8. Create a Loan

  1. Navigate to Origination > Loans
  2. Click Create
  3. Fill in:
    • Borrower: Select the borrower you created
    • Program: Consumer Installment
    • Product: 36-Month Fixed Personal Loan
    • Principal Amount: 10000
    • Interest Rate: 0.085
    • Term: 36 months
  4. Save --- the loan is created in pending status

9. Process the Loan

Approve

On the loan's show page, click the Approve action button. This runs compliance checks (if configured) and moves the loan to approved status.

Disburse

  1. Navigate to the Disbursements tab
  2. Click Create Disbursement
  3. Enter the amount and method
  4. Process the disbursement

On completion:

  • An amortization schedule is generated
  • GL entries are posted (DR Loans Receivable, CR Cash)
  • Origination fees are assessed (if configured on the product)
  • The loan moves to active status

Record a Payment

  1. Navigate to the Payments tab on the loan
  2. Click Record Payment
  3. Enter the amount and payment method
  4. Submit

The payment is allocated across fees, interest, and principal per the lending program's allocation order, and corresponding GL entries are posted.

10. View Ledger Entries

Navigate to Accounting > Journal Entries to see all GL entries generated by the disbursement and payment. Each entry shows balanced debit and credit lines.

You can also view loan-specific entries on the Sub-Ledger tab of the loan's show page.

Next Steps