Meridian Ledger

A full-stack knowledge operations platform for owner-scoped knowledge management, asynchronous indexing, grounded retrieval-backed answers, and persisted evaluation workflows.

Problem framing

Operational context is often scattered across notes, runbooks, decisions, and incident follow-ups. That fragmentation weakens recall, makes answers difficult to verify, and creates risk when AI is introduced without grounded evidence or clear reviewability.

Meridian Ledger addresses that problem with a structured internal platform for managing owned knowledge records, indexing them asynchronously, retrieving relevant evidence, generating source-constrained answers, and persisting evaluation artefacts for retrieval and groundedness review.

Why this repository exists

This repository exists to demonstrate production-minded AI and software engineering choices rather than a generic retrieval demo. It emphasizes ownership boundaries, explicit backend and frontend separation, asynchronous workflows, persisted evidence, deterministic local execution, and operator reviewability.

Core workflows

• sign in through a JWT-authenticated SPA
• create, search, filter, edit, and delete owner-scoped knowledge records
• queue full-workspace or single-note reindexing
• ask grounded questions over indexed notes
• inspect supporting sources returned with each answer
• run saved evaluation cases
• review persisted evaluation runs and related notes
• inspect notes, chunks, logs, and evaluation artefacts through Django admin

Architecture overview

Meridian Ledger is split into a Django backend and a React frontend.

Backend

The backend is responsible for:

• authentication and authorization
• PostgreSQL persistence
• owner-scoped note CRUD
• asynchronous indexing with Celery and Redis
• chunking and deterministic local embeddings
• grounded retrieval and answer construction
• query logging
• evaluation case execution and persisted evaluation runs
• operator inspection through Django admin

Frontend

The frontend is responsible for:

• SPA routing and protected routes
• auth state management
• typed API integration
• note management pages
• ask workflow presentation
• evaluation workflow presentation

Retrieval pipeline overview

1. a user creates or updates a note
2. the backend marks the note as needing indexing
3. a Celery task chunks and indexes the note asynchronously
4. the user asks a question
5. indexed chunks for the current owner are ranked by similarity
6. the answer is constructed from retrieved content only
7. supporting sources and query metadata are returned
8. the query is persisted as a QueryLog

Evaluation overview

Meridian Ledger persists evaluation as part of the product, not as a separate notebook exercise.

The system stores:

• EvaluationCase
• EvaluationRun

A case defines:

• a question
• expected keywords
• expected note titles

A run records:

• the linked query
• whether an expected note was hit
• whether groundedness passed
• review notes showing expected versus retrieved evidence

Authentication and authorization

• Django admin uses session authentication
• SPA API access uses JWT
• notes and retrieval are owner-scoped
• evaluation runs listed in the API are filtered to the authenticated user’s query history
• system evaluation cases are available to authenticated users

Repository structure

backend/
frontend/
docs/
.github/
docker-compose.yml
README.md
LICENSE

Local setup

1. Start infrastructure

Run from:

D:\project-mastery\meridian-ledger

docker compose up -d
docker compose ps

To stop infrastructure later, run from the same directory:

docker compose down

2. Prepare the backend

Run from:

D:\project-mastery\meridian-ledger\backend

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements\dev.txt
Copy-Item .env.example .env
python manage.py migrate
python manage.py createsuperuser

To leave the virtual environment later:

deactivate

3. Install frontend dependencies

Run from:

D:\project-mastery\meridian-ledger\frontend

npm install

4. Seed demo data

Run from:

D:\project-mastery\meridian-ledger\backend

.\.venv\Scripts\Activate.ps1
python manage.py shell -c "exec(open('scripts/seed_demo_data.py').read())"

If you enter the Django shell manually, leave it with:

exit()

Environment notes

The real backend environment file is:

D:\project-mastery\meridian-ledger\backend\.env

The example backend environment file is:

D:\project-mastery\meridian-ledger\backend\.env.example

For this local setup, PostgreSQL must remain aligned to the Docker host mapping:

• POSTGRES_PORT=5433

The Docker Compose mapping is:

• "5433:5432"

This should not be reverted unless the local environment is intentionally changed.

Run instructions

Use three terminals.

Terminal 1: Django backend

Run from:

D:\project-mastery\meridian-ledger\backend

.\.venv\Scripts\Activate.ps1
python manage.py runserver

Stop the Django server with CTRL + C.

Terminal 2: Celery worker

Run from:

D:\project-mastery\meridian-ledger\backend

.\.venv\Scripts\Activate.ps1
celery -A config worker -l info --pool=solo

Stop the Celery worker with CTRL + C.

Terminal 3: Frontend

Run from:

D:\project-mastery\meridian-ledger\frontend

npm run dev

Stop the Vite dev server with CTRL + C.

Local URLs

• SPA: http://127.0.0.1:5173
• Django admin: http://127.0.0.1:8000/admin/

Demo credentials

SPA demo user

• username: demo_operator
• password: StrongPassword123

Django admin

Use the superuser created during setup.

Verification commands

Backend

Run from:

D:\project-mastery\meridian-ledger\backend

.\.venv\Scripts\Activate.ps1
python manage.py check
pytest
ruff check .

Frontend

Run from:

D:\project-mastery\meridian-ledger\frontend

npm run test
npm run build

Repository and Docker status

Run from:

D:\project-mastery\meridian-ledger

docker compose ps
git status

Verification scripts

Backend script

Run from:

D:\project-mastery\meridian-ledger\backend

.\.venv\Scripts\Activate.ps1
.\scripts\verify-backend.ps1

Frontend script

Run from:

D:\project-mastery\meridian-ledger\frontend

.\verify-frontend.ps1

If pytest, the Django server, the Celery worker, or the Vite dev server hangs unexpectedly, press CTRL + C and rerun the command from the same directory.

Documentation links

• architecture overview: docs/architecture/overview.md
• retrieval and groundedness evaluation: docs/evaluation/rag-evaluation.md
• evaluation cases: docs/evaluation/evaluation-cases.md
• test strategy: docs/testing/test-strategy.md
• operations runbook: docs/operations/runbook.md
• portfolio case study: docs/case-study/portfolio-case-study.md

Screenshots

All screenshots are stored in:

docs/screenshots/

Login

Dashboard

Create note

Note detail

Ask grounded question

Grounded answer with sources

Admin notes

Evaluation results

Full screenshot pack

• docs/screenshots/01-login-page.png
• docs/screenshots/02-dashboard.png
• docs/screenshots/03-create-note.png
• docs/screenshots/04-note-detail.png
• docs/screenshots/05-edit-note.png
• docs/screenshots/06-delete-note.png
• docs/screenshots/07-ask-grounded-question.png
• docs/screenshots/08-grounded-answer-with-sources.png
• docs/screenshots/09-admin-notes.png
• docs/screenshots/10-admin-query-logs.png
• docs/screenshots/11-evaluation-results.png
• docs/screenshots/12-backend-tests.png
• docs/screenshots/13-frontend-tests.png
• docs/screenshots/14-ci-success.png

Project narrative alignment

Meridian Ledger is the retrieval and knowledge-assurance project in the broader portfolio. It complements systems centered on governance, compliance, and decision reliability by focusing on the internal knowledge substrate those systems often depend on: owned context capture, indexing, retrieval, source-visible answer generation, and persisted evaluation.

License

This repository is licensed under the MIT License. See the LICENSE file for full details.