diff --git a/db_deploy.sql b/db_deploy.sql
index 2a47acf..e487127 100644
--- a/db_deploy.sql
+++ b/db_deploy.sql
@@ -15,6 +15,7 @@ CREATE TABLE evt.bpr (
     ,bprh JSONB
     ,stmp timestamptz
 );
+COMMENT ON TABLE evt.bpr IS 'log of events';
 COMMENT ON COLUMN evt.bpr.bpr IS 'basic pecuniary record';
 COMMENT ON COLUMN evt.bpr.bprh IS 'basic pecuniary record history';
 COMMENT ON COLUMN evt.bpr.stmp IS 'insert time';
@@ -26,6 +27,7 @@ CREATE TABLE evt.acct (
     acct ltree PRIMARY KEY
     ,prop jsonb
 );
+COMMENT ON TABLE evt.acct IS 'account master list';
 COMMENT ON COLUMN evt.acct.acct IS 'account';
 COMMENT ON COLUMN evt.acct.prop IS 'properties';
 
@@ -35,7 +37,7 @@ CREATE TABLE evt.fspr (
     ,dur tstzrange
     ,prop jsonb
 );
-
+COMMENT ON TABLE evt.fspr IS 'fiscal period definitions';
 COMMENT ON COLUMN evt.fspr.id IS 'fiscal period';
 COMMENT ON COLUMN evt.fspr.dur IS 'duration of period as timestamp range';
 COMMENT ON COLUMN evt.fspr.prop IS 'period properties';
@@ -57,6 +59,7 @@ CREATE TABLE evt.gl (
     ,glline INT
     ,bprkeys JSONB
 );
+COMMENT ON TABLE evt.gl IS 'double entry bpr perspective';
 COMMENT ON COLUMN evt.gl.id IS 'gl id';
 COMMENT ON COLUMN evt.gl.bprid IS 'id of initial basic pecuniary record';
 COMMENT ON COLUMN evt.gl.acct IS 'account code';
@@ -78,6 +81,7 @@ CREATE TABLE evt.bal (
     ,cbal numeric(12,2)
     ,prop jsonb
 );
+COMMENT ON TABLE evt.bal IS 'account balances by fiscal period';
 ALTER TABLE evt.bal ADD CONSTRAINT bal_pk PRIMARY KEY(acct,fspr);
 COMMENT ON COLUMN evt.bal.acct IS 'account';
 COMMENT ON COLUMN evt.bal.fspr IS 'period';
@@ -165,7 +169,8 @@ CREATE OR REPLACE FUNCTION evt.log_insert() RETURNS trigger
     RETURN NULL;
     END;
     $func$;
-    
+
+COMMENT ON FUNCTION evt.log_insert IS 'add rows to relevant perspectives for new bpr';
 
 CREATE TRIGGER log_insert 
     AFTER INSERT ON evt.bpr
@@ -308,6 +313,8 @@ BEGIN
 END;
 $func$;
 
+COMMENT ON FUNCTION evt.gl_insert IS 'update evt.bal with new ledger rows';
+
 CREATE TRIGGER gl_insert 
     AFTER INSERT ON evt.gl
     REFERENCING NEW TABLE AS ins
@@ -443,6 +450,8 @@ BEGIN
 END;
 $func$;
 
+COMMENT ON FUNCTION evt.balrf() IS 'close any gaps and ensure all accounts roll forward';
+
 ------------------------json concetenate aggregate-------------------------------------------
 
 CREATE OR REPLACE FUNCTION evt.jsonb_concat(
diff --git a/schema/functions/rollforward.sql b/schema/functions/rollforward.sql
index 672a89e..1ee5991 100644
--- a/schema/functions/rollforward.sql
+++ b/schema/functions/rollforward.sql
@@ -122,4 +122,6 @@ BEGIN
     WHERE
         t.fspr = f.id;
 END;
-$func$;
\ No newline at end of file
+$func$;
+
+COMMENT ON FUNCTION evt.balrf() IS 'close any gaps and ensure all accounts roll forward';
\ No newline at end of file
diff --git a/schema/tables/acct.sql b/schema/tables/acct.sql
index 56bb1aa..77ce91a 100644
--- a/schema/tables/acct.sql
+++ b/schema/tables/acct.sql
@@ -5,5 +5,6 @@ CREATE TABLE evt.acct (
     acct ltree PRIMARY KEY
     ,prop jsonb
 );
+COMMENT ON TABLE evt.acct IS 'account master list';
 COMMENT ON COLUMN evt.acct.acct IS 'account';
-COMMENT ON COLUMN evt.acct.prop IS 'properties';
\ No newline at end of file
+COMMENT ON COLUMN evt.acct.prop IS 'properties';
diff --git a/schema/tables/bal.sql b/schema/tables/bal.sql
index 82211a2..efd4205 100644
--- a/schema/tables/bal.sql
+++ b/schema/tables/bal.sql
@@ -10,6 +10,7 @@ CREATE TABLE evt.bal (
     ,prop jsonb
 );
 ALTER TABLE evt.bal ADD CONSTRAINT bal_pk PRIMARY KEY(acct,fspr);
+COMMENT ON TABLE evt.bal IS 'account balances by fiscal period';
 COMMENT ON COLUMN evt.bal.acct IS 'account';
 COMMENT ON COLUMN evt.bal.fspr IS 'period';
 COMMENT ON COLUMN evt.bal.obal IS 'opening balance';
diff --git a/schema/tables/bpr.sql b/schema/tables/bpr.sql
index b82aa46..20dad77 100644
--- a/schema/tables/bpr.sql
+++ b/schema/tables/bpr.sql
@@ -6,6 +6,7 @@ CREATE TABLE evt.bpr (
     ,bprh JSONB
     ,stmp timestamptz
 );
+COMMENT ON TABLE evt.bpr IS 'log of events';
 COMMENT ON COLUMN evt.bpr.bpr IS 'basic pecuniary record';
-COMMENT ON COLUMN evt.bpr.bprh IS 'basic pecuniary record history';
+COMMENT ON COLUMN evt.bpr.bprh IS 'history';
 COMMENT ON COLUMN evt.bpr.stmp IS 'insert time';
\ No newline at end of file
diff --git a/schema/tables/fspr.sql b/schema/tables/fspr.sql
index bb42bbc..e860746 100644
--- a/schema/tables/fspr.sql
+++ b/schema/tables/fspr.sql
@@ -4,7 +4,7 @@ CREATE TABLE evt.fspr (
     ,dur tstzrange
     ,prop jsonb
 );
-
+COMMENT ON TABLE evt.fspr IS 'fiscal period definitions';
 COMMENT ON COLUMN evt.fspr.id IS 'fiscal period';
 COMMENT ON COLUMN evt.fspr.dur IS 'duration of period as timestamp range';
 COMMENT ON COLUMN evt.fspr.prop IS 'period properties';
diff --git a/schema/tables/gl.sql b/schema/tables/gl.sql
index 27d23ec..9d81acb 100644
--- a/schema/tables/gl.sql
+++ b/schema/tables/gl.sql
@@ -12,6 +12,7 @@ CREATE TABLE evt.gl (
     ,glline INT
     ,bprkeys JSONB
 );
+COMMENT ON TABLE evt.gl IS 'double entry bpr perspective';
 COMMENT ON COLUMN evt.gl.id IS 'gl id';
 COMMENT ON COLUMN evt.gl.bprid IS 'id of initial basic pecuniary record';
 COMMENT ON COLUMN evt.gl.acct IS 'account code';
diff --git a/schema/triggers/gl_insert.sql b/schema/triggers/gl_insert.sql
index 4a2d37d..19690cd 100644
--- a/schema/triggers/gl_insert.sql
+++ b/schema/triggers/gl_insert.sql
@@ -133,6 +133,8 @@ BEGIN
 END;
 $func$;
 
+COMMENT ON FUNCTION evt.gl_insert IS 'update evt.bal with new ledger rows';
+
 CREATE TRIGGER gl_insert 
     AFTER INSERT ON evt.gl
     REFERENCING NEW TABLE AS ins
diff --git a/schema/triggers/log_insert.sql b/schema/triggers/log_insert.sql
index 58059f8..5092408 100644
--- a/schema/triggers/log_insert.sql
+++ b/schema/triggers/log_insert.sql
@@ -76,6 +76,7 @@ CREATE OR REPLACE FUNCTION evt.log_insert() RETURNS trigger
     END;
     $func$;
     
+COMMENT ON FUNCTION evt.log_insert IS 'add rows to relevant perspectives for new bpr';
 
 CREATE TRIGGER log_insert 
     AFTER INSERT ON evt.bpr