Top Tier Financial Solutions

Top Tier Financial Solutions is a full-stack credit repair operations platform for managing the complete client journey from lead intake through onboarding, dispute execution, response review, progress reporting, and compliant billing readiness.

The application is designed for a credit repair business that needs more than a generic CRM. It tracks regulated workflow gates, protects client PII, keeps dispute strategy auditable, separates internal operations metrics from client outcome claims, and prevents billing from moving ahead of documented services rendered.

The platform coordinates three connected experiences:

• Public website for prospects, educational content, contact forms, service information, FAQs, testimonials, newsletter capture, and scheduling.
• Admin dashboard for staff managing leads, clients, documents, agreements, disputes, billing readiness, analytics, tasks, and content.
• Client portal for secure collaboration, onboarding documents, agreement review, progress visibility, messages, audit reports, notification preferences, and required confirmations.

The core product is the credit repair operating workflow. The system models client service relationships, compliance gates, dispute cycles, credit report pulls, response reviews, service-rendered events, and audit-friendly payment readiness.

• Business owner: configures services, monitors operations, reviews analytics, manages staff access, and confirms that compliance gates are enforced.
• Manager: oversees the client pipeline, work queues, response aging, billing readiness, and service quality.
• Dispute specialist: reviews reports, builds evidence-backed dispute strategy, generates letters from approved policy inputs, records submissions, and reviews responses.
• Onboarding specialist: ensures agreements, disclosures, identity documents, proof of address, and credit report access requirements are complete before service work begins.
• Billing staff: tracks invoices, payment status, services rendered, and audit trail details without charging before required billing locks are satisfied.
• Client: signs agreements, uploads documents, reviews progress, messages the team, and confirms high-risk factual claims when required.

The canonical lifecycle starts with a lead and moves through consultation, qualification, agreement, cancellation window, onboarding, active dispute work, response review, next-cycle decisions, maintenance, and closure.

Important workflow concepts:

• Service Engagement: the service relationship between the business and a client. Credit Audit and Credit Restoration are modeled separately.
• Compliance Gate: the required checks before a client reaches Ready for First Work.
• Cancellation Window: the period where internal preparation may happen, but external execution, services-rendered marking, payable invoices, and charging are blocked.
• Dispute Cycle: one coordinated round of dispute work from item selection through submission, response tracking, response review, and next decision.
• Evidence Packet: the documents and client confirmations attached to a specific dispute claim.
• Credit Report Pull: a report import at a point in time, used for comparison, progress tracking, and outcome analysis.
• Response Review: the structured review of bureau, furnisher, collector, creditor, or regulator responses before closing, updating, escalating, or continuing an item.
• Services Rendered: a concrete completed service event that can support compliant invoicing.

• Client and lead management across the credit repair lifecycle.
• Staff work queues for onboarding blockers, dispute work, response deadlines, messages, and billing readiness.
• Role and permission checks for sensitive admin actions.
• Content management for public pages, services, blog posts, FAQs, testimonials, disclaimers, and agreements.
• Operational analytics separated from client-facing outcome analytics.

• Service Engagement records for distinct service scopes.
• Compliance Gate checks before work can begin.
• CROA-oriented agreement and cancellation-window handling.
• Services Rendered records for billing support.
• Payable invoice checks that require qualifying services-rendered events.
• Credit Audit billing separated from Credit Restoration billing.
• Payment audit logs that explain why an invoice became payable.
• Live charging intentionally deferred until required billing locks are enforced.

• Deterministic parsing for supported credit report formats.
• Credit Report Pull history and comparison across bureaus.
• Detection of deleted, updated, unchanged, and newly added negative items.
• Bureau-level score and item progress tracking where report data supports it.
• Deterministic dispute policy decisions before letter generation.
• AI-assisted letter rendering limited to approved policy inputs.
• Dispute targeting for the big-3 bureaus plus secondary consumer reporting agencies (LexisNexis, Innovis, ChexSystems, Early Warning Services).
• FCRA 7-year obsolescence tracking keyed to Date of First Delinquency where available.
• Per-creditor strategy success analytics with historical methodology recommendations surfaced in triage (advisory only; policy still gates).
• Submission Tracking for manual mail details, recipients, dates, tracking numbers, proof documents, delivery status, and response deadlines.
• Response Review with structured outcomes and next-cycle recommendations.

• Mobile-responsive portal experience.
• Agreement review and signing.
• Required onboarding document checklist.
• Secure document upload flow.
• Client-visible progress snapshot derived from operational records.
• Secure portal messaging and notification preferences.
• Explicit client confirmation for high-risk factual claims.
• Audit and progress report visibility after staff release approval.

• Better Auth authentication with admin role handling.
• Explicit admin permissions for sensitive workflow areas.
• PII encryption boundaries for client data.
• PII minimization in list responses and client-facing views.
• Sanitized rendered HTML before display.
• CSP hardening for rendered pages.
• Cloudflare R2-compatible object storage for controlled file handling.
• Rate limiting support through Upstash packages.
• Sentry integration for production monitoring.

AI is used as a letter renderer, not as a policy decision-maker.

The application must decide dispute eligibility, reason codes, claim risk, target recipients, required evidence, and escalation paths with deterministic code before calling an AI provider. AI-generated text must be traceable to approved policy inputs and must not invent facts, upgrade claims, or create unsupported guarantees.

The interface runs on one design language — "Midnight & Brass" — across the public marketing site, the admin SaaS console, and the client portal. It pairs a warm paper canvas with dark ink "bookends" (header + footer) and a single brass accent, built for a regulated financial product: editorial where it persuades, dense where it operates, restrained everywhere.

• Palette: warm stone/paper neutrals, near-black warm ink, a single brass accent. Green and red are reserved for data signals (deltas, credit-score bands) and risk states — never decoration.
• Typography: Instrument Serif for editorial headlines (.font-editorial), self-hosted Satoshi for UI and body, Geist Mono for numbers, labels, and eyebrows.
• Tokens: defined in src/app/globals.css (:root light, .dark dark) and exposed to Tailwind v4 via @theme inline. Use semantic utilities (bg-secondary, text-muted-foreground, border-border) — never hardcoded hex.
• Admin shell: the console is a "paper sheet on an ink desk" — a locked full-viewport ink surface carrying a flat, single-level sidebar, with the workspace as a raised, rounded paper sheet that owns its own scroll region. Admin page titles use the editorial serif, tying the product to the marketing voice.
• Shared components: AdminPageHeader and StatGrid standardize admin page headers and stat strips; MetricTile, ScoreBadge, StatusBadge, and DataTable cover dense data display. Card titles are compact (text-sm font-semibold); numbers are always mono tabular.
• Motion: crisp, custom ease-out, under ~300ms, interruptible. No infinite-loop decoration; Framer Motion is reserved for modal/drawer enter-exit.

See docs/DESIGN-SYSTEM.md for the full token table, component reference, and usage rules, and brand-spec.md for the brand summary.

• Frontend: Next.js 16, React 19, TypeScript, Tailwind CSS v4. Typography: Satoshi (self-hosted) + Instrument Serif + Geist Mono. Framer Motion for modal/transition motion only (ambient/decorative animation is static CSS).
• Backend: Next.js App Router and API routes as the primary application backend.
• Legacy service: optional Python FastAPI backend for older or auxiliary workflows.
• Database: Neon PostgreSQL with Drizzle ORM and Drizzle Kit migrations.
• Authentication: Better Auth.
• File storage: Cloudflare R2 using S3-compatible APIs.
• AI providers: Google Gemini, OpenAI, Anthropic Claude, and Zhipu are supported for letter rendering, selectable in admin LLM settings; deterministic policy remains the source of truth.
• Scheduling and booking: Cal.com integration for prospect scheduling.
• Observability: Sentry for Next.js.
• Testing: Vitest, Testing Library, Playwright tooling.

Install dependencies:

npm install

Create environment configuration:

cp env.example .env

Edit the environment file with local credentials. At minimum, local development usually needs a database URL, Better Auth secret, app URL, storage credentials for document flows, and AI keys for generation features.

Run database migrations:

npm run db:migrate

Start the Next.js development server:

npm run dev

Start the optional legacy FastAPI service only when working on Python-backed flows:

npm run fastapi-dev

Use env.example as the source of truth for required variables.

Commonly used variables include:

• DATABASE_URL: Neon PostgreSQL connection string.
• BETTER_AUTH_SECRET: Better Auth secret with sufficient entropy.
• NEXT_PUBLIC_APP_URL: public app URL used by auth and links.
• R2_*: Cloudflare R2 credentials and bucket configuration.
• GOOGLE_AI_API_KEY: Gemini API key for AI-assisted generation.
• OPENAI_API_KEY: OpenAI API key where OpenAI-backed features are enabled.
• NEXT_PUBLIC_CAL_*: Cal.com scheduling integration settings.
• SENTRY_*: Sentry monitoring configuration where enabled.

Never commit secrets. Use local environment files for development and managed environment variables in deployment.

npm run dev            # Start the Next.js development server
npm run fastapi-dev    # Start the optional legacy FastAPI backend
npm run build          # Build the production Next.js app
npm run start          # Start the production server after build
npm run lint           # Run ESLint
npm run typecheck      # Run TypeScript without emitting files
npm run test           # Run the Vitest test suite
npm run test:e2e       # Run Playwright end-to-end tests
npm run validate       # Run lint, typecheck, tests, and build
npm run db:generate    # Generate Drizzle migrations from schema changes
npm run db:migrate     # Apply Drizzle migrations (the only supported path — see docs/DATABASE.md)
npm run db:push        # DO NOT USE: would drop the FastAPI admin_users table (see docs/DATABASE.md)
npm run db:studio      # Open Drizzle Studio

api/              Optional legacy Python FastAPI backend
db/               Database schema and database client setup
drizzle/          Generated SQL migrations and migration metadata
public/           Static assets served by Next.js
scripts/          Utility scripts for migration and maintenance tasks
src/app/          Next.js routes, public pages, admin pages, portal pages, and API routes
src/components/   React components for admin, portal, public pages, and shared UI
src/hooks/        Client-side hooks used by workflow UI
src/lib/          Domain logic, parsers, auth helpers, security utilities, and service code
src/__tests__/    API, component, integration, parser, and library tests
docs/             Implementation notes, plans, parser guides, and production readiness notes
specs/            Project specifications and supporting product documents

• Treat CONTEXT.md as the domain glossary for service lifecycle and compliance language.
• Keep policy decisions deterministic and testable.
• Keep AI behind approved policy inputs.
• Keep client portal behavior collaborative, not operationally editable.
• Keep Operator Analytics separate from Client Outcome Analytics.
• Keep billing tied to Services Rendered and compliance gates.
• Keep PII encrypted or minimized unless a workflow explicitly requires decrypted values.
• Prefer small schema changes and generated migrations over broad rewrites.
• Change the database only through db:generate + db:migrate — never db:push, and never hand-applied SQL without bookkeeping (see docs/DATABASE.md).
• Run focused tests for the touched area before broad validation.

Before production release or major handoff, run:

npm run validate

For dependency security gates, run:

npm audit --audit-level=high

Current production-readiness notes are tracked in the production readiness blocker document linked below.

• Setup Guide - detailed local setup and environment guidance.
• Design System - "Midnight & Brass" tokens, shared components, admin shell pattern, typography, and motion rules.
• Brand Spec - logo, palette, and brand summary.
• Database & Migrations - Drizzle workflow, migration-history notes, and why db:push is forbidden.
• Domain Context - canonical project glossary and workflow language.
• Credit Repair Platform Roadmap - implementation sequence and acceptance criteria.
• Production Readiness Blockers - current release blockers, warnings, and audit status.
• Credit Analysis Implementation - credit report analysis implementation details.
• Secondary Bureaus And Creditor Analytics - secondary CRA dispute support, per-creditor strategy analytics, and FCRA accuracy fixes.
• IdentityIQ Parser Guide - parser-specific guidance for IdentityIQ reports.

Private - All rights reserved.