feat: add LHCI workflow, onboarding UI, penalties support

.github/workflows/lighthouse-ci.yml

@@ -0,0 +1,29 @@
+name: Lighthouse CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  lighthouse:
+    name: Lighthouse CI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Build
+        run: |
+          npm run build
+          npm run export || true
+      - name: Run LHCI autorun
+        env:
+          LHCI_GITHUB_COMMIT_SHA: ${{ github.sha }}
+        run: |
+          npx -y @lhci/cli autorun --config=.lighthouserc.json --upload.target=temporary-public-storage

.lighthouserc.json

@@ -0,0 +1,15 @@
+{
+  "ci": {
+    "collect": {
+      "url": ["http://localhost:8080"],
+      "startServerCommand": "npx serve out -l 8080"
+    },
+    "assert": {
+      "assertions": {
+        "categories:performance": ["error", { "minScore": 0.85 }],
+        "categories:accessibility": ["error", { "minScore": 0.90 }]
+      }
+    },
+    "upload": { "target": "temporary-public-storage" }
+  }
+}

migrations/1749000000000_add-penalties-table.ts

@@ -0,0 +1,18 @@
+import { MigrationBuilder } from "node-pg-migrate";
+
+export async function up(pgm: MigrationBuilder): Promise<void> {
+  pgm.createTable("penalties", {
+    id: { type: "uuid", primaryKey: true, default: pgm.func("gen_random_uuid()") },
+    circle_id: { type: "uuid", notNull: true, references: "circles(id)", onDelete: "CASCADE" },
+    member_id: { type: "uuid", notNull: true, references: "members(id)", onDelete: "CASCADE" },
+    cycle_number: { type: "integer", notNull: true },
+    amount_usdc: { type: "numeric(20,7)", notNull: true },
+    created_at: { type: "timestamp", notNull: true, default: pgm.func("NOW()") },
+  });
+  pgm.createIndex("penalties", ["circle_id"]);
+  pgm.createIndex("penalties", ["member_id"]);
+}
+
+export async function down(pgm: MigrationBuilder): Promise<void> {
+  pgm.dropTable("penalties");
+}

src/components/Onboarding.tsx

@@ -0,0 +1,65 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import styles from "./Onboarding.module.css";
+
+const STORAGE_KEY = "ajosave:onboarding";
+
+export function Onboarding({ onClose }: { onClose?: () => void }) {
+  const [step, setStep] = useState<number>(0);
+  const [inProgress, setInProgress] = useState<any>(() => {
+    try {
+      return JSON.parse(localStorage.getItem(STORAGE_KEY) || "null") || { seen: false, step: 0 };
+    } catch { return { seen: false, step: 0 }; }
+  });
+
+  useEffect(() => {
+    setStep(inProgress.step || 0);
+  }, []);
+
+  useEffect(() => {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify({ ...inProgress, step }));
+  }, [step]);
+
+  const finish = (seen = true) => {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify({ seen: seen, step }));
+    onClose?.();
+  };
+
+  return (
+    <div className={styles.backdrop} role="dialog" aria-modal="true">
+      <div className={styles.card}>
+        <h2>Welcome to Ajosave</h2>
+        <div className={styles.content}>
+          {step === 0 && (
+            <div>
+              <h3>What is Ajo?</h3>
+              <p>Rotating savings circles powered by Stellar and USDC — pool funds, take turns receiving the pot.</p>
+            </div>
+          )}
+          {step === 1 && (
+            <div>
+              <h3>Connect Wallet</h3>
+              <p>Connect your Stellar wallet (Freighter) to send/receive USDC on-chain.</p>
+            </div>
+          )}
+          {step === 2 && (
+            <div>
+              <h3>Make Your First Contribution</h3>
+              <p>Create or join a circle and contribute USDC to start saving together.</p>
+            </div>
+          )}
+        </div>
+
+        <div className={styles.controls}>
+          <button className="btn btn--ghost" onClick={() => { finish(false); }}>Skip</button>
+          <div>
+            {step > 0 && <button className="btn btn--ghost" onClick={() => setStep(s => Math.max(0, s - 1))}>Back</button>}
+            {step < 2 && <button className="btn btn--primary" onClick={() => setStep(s => s + 1)}>Next</button>}
+            {step === 2 && <button className="btn btn--primary" onClick={() => finish(true)}>Done</button>}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

src/components/circle/CreateCircleForm.tsx

@@ -15,6 +15,8 @@ const FORM_DEFAULTS: Partial<CreateCircleInput> = {
   cycleFrequency: "monthly",
   circleType: "public",
   contributionCurrency: "NGN",
+  yieldStrategy: "none",
+  penaltyPercent: 10,
 };
 
 function useUsdcPreview(amount: number | undefined, currency: string) {

src/components/dashboard/LiveDashboard.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useState } from "react";
+import { useCallback, useState, useEffect } from "react";
 import type { Circle } from "@/types";
 import { CircleCard } from "@/components/circle/CircleCard";
 import { ConnectionStatus } from "@/components/ui/ConnectionStatus";
@@ -17,6 +17,7 @@ export function LiveDashboard({ initialCircles }: LiveDashboardProps) {
   const [circles, setCircles] = useState<Circle[]>(initialCircles);
   const [lastUpdate, setLastUpdate] = useState<Date | null>(null);
   const [newCirclesCount, setNewCirclesCount] = useState(0);
+  const [showOnboarding, setShowOnboarding] = useState(false);
 
   const fetchCircles = useCallback(async () => {
     const res = await fetch("/api/circles?filter=mine");
@@ -41,6 +42,14 @@ export function LiveDashboard({ initialCircles }: LiveDashboardProps) {
     },
   });
 
+  useEffect(() => {
+    try {
+      const stored = localStorage.getItem("ajosave:onboarding");
+      const parsed = stored ? JSON.parse(stored) : null;
+      if (!parsed?.seen) setShowOnboarding(true);
+    } catch {}
+  }, []);
+
   return (
     <>
       <div className={styles.header}>
@@ -76,6 +85,12 @@ export function LiveDashboard({ initialCircles }: LiveDashboardProps) {
           ))}
         </div>
       )}
+
+      {showOnboarding && (
+        // Lazy-load to keep bundle small
+        //@ts-ignore
+        <Onboarding onClose={() => setShowOnboarding(false)} />
+      )}
     </>
   );
 }

src/server/services/circle.service.ts

@@ -23,6 +23,8 @@ const CIRCLE_SELECT = `
   payout_method as "payoutMethod", 
   randomization_seed as "randomizationSeed",
   grace_period_hours as "gracePeriodHours",
+  yield_strategy as "yieldStrategy",
+  penalty_percent as "penaltyPercent",
   status, contract_id as "contractId", 
   current_cycle as "currentCycle", 
   (SELECT COUNT(*)::int FROM members WHERE circle_id = circles.id AND status = 'active') as "memberCount",
@@ -58,11 +60,11 @@ export async function createCircle(
   const { rows } = await query<Circle>(
     `INSERT INTO circles
        (id, name, creator_id, contribution_usdc, contribution_fiat, contribution_currency,
-        max_members, cycle_frequency, payout_method, contract_id, grace_period_hours, status, current_cycle, created_at, updated_at)
-     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,'open',0,NOW(),NOW())
+        max_members, cycle_frequency, payout_method, randomization_seed, yield_strategy, penalty_percent, contract_id, grace_period_hours, status, current_cycle, created_at, updated_at)
+     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,'open',0,NOW(),NOW())
      RETURNING ${CIRCLE_SELECT}`,
     [id, input.name, creatorId, contributionUsdc, input.contributionAmount, input.contributionCurrency,
-     input.maxMembers, input.cycleFrequency, input.payoutMethod, contractId, input.gracePeriodHours ?? 24]
+     input.maxMembers, input.cycleFrequency, input.payoutMethod, null, input.yieldStrategy, input.penaltyPercent, contractId, input.gracePeriodHours ?? 24]
   );
   return rows[0];
 }
@@ -164,6 +166,9 @@ export async function getCirclesByUser(userId: string): Promise<Circle[]> {
         c.cycle_frequency as "cycleFrequency", 
         c.payout_method as "payoutMethod", 
         c.randomization_seed as "randomizationSeed",
+        c.grace_period_hours as "gracePeriodHours",
+        c.yield_strategy as "yieldStrategy",
+        c.penalty_percent as "penaltyPercent",
         c.status, c.contract_id as "contractId", 
         c.current_cycle as "currentCycle", 
         c.next_payout_at as "nextPayoutAt", 

src/server/services/notification.service.ts

@@ -194,6 +194,27 @@ export async function toggleSmsNotifications(
   );
 }
 
+/**
+ * Notify circle creator (admin) that a member defaulted and a penalty was recorded.
+ */
+export async function notifyAdminOfDefault(
+  adminUserId: string,
+  defaulterUserId: string,
+  circleName: string,
+  penaltyAmount: string
+): Promise<void> {
+  if (!(await canSendSms(adminUserId))) return;
+  const phone = await getUserPhone(adminUserId);
+  if (!phone) return;
+
+  try {
+    const message = `Ajosave: A member defaulted in "${circleName}". Penalty of ${penaltyAmount} USDC recorded.`;
+    await sendSms(phone, message);
+  } catch (error) {
+    console.error(`Failed to notify admin ${adminUserId} about default:`, error);
+  }
+}
+
 /**
  * Notify all circle members when the circle completes (all payouts done)
  */

src/server/services/scheduler.service.ts

@@ -90,8 +90,30 @@ export async function processMissedContributions(): Promise<void> {
           [userId]
         );
 
-        // Send notification
+        // Apply configurable penalty (record in penalties table)
+        try {
+          const penaltyPercent = Number((circle as any).penalty_percent ?? (circle as any).penaltyPercent ?? 10);
+          const penaltyAmount = (parseFloat(circle.contributionUsdc) * (penaltyPercent / 100)).toFixed(7);
+          await query(
+            `INSERT INTO penalties (circle_id, member_id, cycle_number, amount_usdc, created_at)
+             VALUES ($1,$2,$3,$4,NOW())`,
+            [circle.id, memberId, circle.currentCycle, penaltyAmount]
+          );
+        } catch (err) {
+          console.error("Failed to record penalty for defaulted member:", err);
+        }
+
+        // Send notification to member and notify creator (admin)
         await notifyMissedContribution(userId, circle.name, circle.contributionUsdc);
+        try {
+          const creatorId = (circle as any).creator_id ?? (circle as any).creatorId;
+          if (creatorId) {
+            const { notifyAdminOfDefault } = await import("@/server/services/notification.service");
+            await notifyAdminOfDefault(creatorId, userId, circle.name, (parseFloat(circle.contributionUsdc) * (Number((circle as any).penalty_percent ?? (circle as any).penaltyPercent ?? 10) / 100)).toFixed(7));
+          }
+        } catch (err) {
+          console.error("Failed to notify circle admin about default:", err);
+        }
       }
     } catch (error) {
       console.error(`Failed to process missed contributions for circle ${circle.id}:`, error);

src/types/index.ts

@@ -40,6 +40,8 @@ export interface Circle {
   nextPayoutAt?: Date;
   pausedAt?: Date | null;
   minReputation?: number; // minimum reputation score required to join (0-100)
+  yieldStrategy?: "none" | "blend";
+  penaltyPercent?: number;
   createdAt: Date;
   updatedAt: Date;
   deletedAt?: Date | null; // soft delete timestamp

src/types/schemas.ts

@@ -14,6 +14,8 @@ export const createCircleSchema = z.object({
   circleType: z.enum(["public", "private"]).default("public"),
   gracePeriodHours: z.number().int().min(0).max(168).default(24),
   payoutMethod: z.enum(["fixed", "randomized"]).default("fixed"),
+  yieldStrategy: z.enum(["none", "blend"]).default("none"),
+  penaltyPercent: z.number().int().min(0).max(100).default(10),
 });
 
 export const joinCircleSchema = z.object({