credit-repair-app

Imported from widescopeindustries/credit-repair-app (AGENTS.md). Install upstream with npx skills add widescopeindustries/credit-repair-app. Copyright stays with the author.

Agent Guidelines for Credit Repair AI

This document provides guidelines for agentic coding assistants working on this repository.

Build & Development Commands

Running the Application

# Start the development server (recommended)
python run.py

# Alternative: Start FastAPI server directly
python -m uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

Setup & Dependencies

# Create and activate virtual environment
cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r backend/requirements.txt

# Configure environment (copy .env.example to .env)
cp backend/.env.example backend/.env

Testing

# Note: This project currently has no test suite
# When adding tests, use pytest (not currently configured)
# Run single test: pytest tests/test_module.py::test_function_name

Code Style Guidelines

Python Backend (FastAPI)

Imports:

• Import order: standard library → third-party → local modules
• Use relative imports for local backend modules: from ..models.schemas import ...
• Group imports with one blank line between each group
• Avoid wildcard imports (import *)

Formatting & Types:

• Use snake_case for functions, variables, and module names
• Use PascalCase for classes and type names
• Use UPPERCASE for constants (though mostly handled via Enum)
• All functions should use type hints (def func(arg: Type) -> ReturnType:)
• Use typing module for complex types: List, Dict, Optional, Union
• Use Pydantic for data validation and serialization
• Use str, Enum for enum classes to ensure JSON serializable values

Naming Conventions:

• Classes: PascalCase (e.g., CreditAnalysisService)
• Functions/Methods: snake_case (e.g., analyze_reports)
• Private methods: prefix with underscore (e.g., _parse_accounts)
• Constants: UPPERCASE (use Enum instead when possible)
• Variables: snake_case (e.g., credit_score, account_number)
• API routes: kebab-case for URL paths (e.g., /upload-report)

Error Handling:

• Use try-except blocks for external API calls and file operations
• Raise specific exceptions with descriptive messages
• Use FastAPI's HTTPException for API errors (400, 404, 500 status codes)
• Log errors appropriately (consider adding logging in future)
• Gracefully handle missing data (use Optional types, default values)

Async/Await:

• Use async/await for all FastAPI route handlers
• Use async for I/O operations (file reads, network calls)
• Keep CPU-bound operations synchronous or use thread pool

Class Structure:

• One class per file when possible (services, models)
• Use __init__ for initialization, define dependencies as instance variables
• Prefix private/internal methods with underscore
• Use Pydantic BaseModel for all data structures
• Keep business logic in service layer, not in route handlers

API Design:

• Use Pydantic models for request/response bodies
• Use Form for form data, File for uploads
• Return structured JSON responses (dictionaries or model dicts)
• Use descriptive HTTP status codes (200, 201, 400, 404, 500)
• Add CORS middleware for local development

Frontend (HTML/CSS/JavaScript)

HTML:

• Use semantic HTML5 elements
• Inline CSS in <style> blocks in templates (no external CSS files)
• Use double quotes for attributes
• Self-closing void elements: <br>, <hr>, <input>, <img>

CSS:

• Use camelCase for class names or kebab-case (be consistent)
• Use CSS Grid and Flexbox for layouts
• Mobile-first responsive design
• Use CSS variables for repeated values (colors, spacing)
• Use specific classes, not element selectors for scoped styling

JavaScript:

• Use const and let, never var
• Use arrow functions for callbacks and event handlers
• Use template literals for string interpolation
• Use async/await for all API calls
• Use fetch API for HTTP requests
• Store state in variables or objects (no framework state management)
• DOM manipulation: use document.getElementById, querySelector
• Event handlers can be inline in HTML for simplicity

API Calls:

• Use FormData for file uploads
• Use JSON for data payloads
• Handle both success and error cases
• Show loading indicators during async operations
• Parse responses as JSON: response.json()

Project Structure & Patterns

credit-repair-app/
├── backend/
│   ├── api/           # FastAPI route handlers (endpoints)
│   ├── models/        # Pydantic schemas and data models
│   ├── services/      # Business logic (parser, analyzer, generator)
│   ├── utils/         # Utility functions (currently empty)
│   ├── config.py      # Configuration using pydantic-settings
│   └── requirements.txt
├── frontend/
│   ├── templates/     # HTML templates
│   └── static/        # CSS, JS, images (currently empty)
├── uploads/           # Uploaded PDF files (runtime)
├── disputes/          # Generated dispute letters (runtime)
├── data/              # Local data storage (runtime)
└── run.py            # Entry point script

Key Patterns:

• Route handlers in api/main.py should be thin, delegate to services
• Services contain business logic, can be reused
• Models define data contracts, used for validation
• Configuration centralized in config.py via Settings class
• Data persisted locally (no database currently)

Configuration

• Environment variables in .env file (create from .env.example)
• Settings managed via pydantic-settings in backend/config.py
• OpenAI API key is optional, app works without it
• Directories: uploads/, disputes/, data/ created at runtime

Privacy & Security

• All user data stored locally only
• No external data transmission (except optional OpenAI API)
• Credit reports never sent to external services
• Do not add cloud storage or third-party analytics
• Never commit .env file or sensitive data to git
• Validate all file uploads (PDF only, file size limits)

Adding New Features

1. Create/update Pydantic models in models/schemas.py
2. Implement business logic in appropriate service file
3. Add API endpoint in api/main.py (or create new file)
4. Update frontend HTML/CSS/JS as needed
5. Test manually via browser at http://localhost:8000
6. Update README.md if user-facing

Code to Avoid

• Do not add frameworks (React, Vue, Django, etc.)
• Do not add databases (use local file system)
• Do not add authentication/authorization unless explicitly requested
• Do not use complex class hierarchies or inheritance
• Do not add unit/integration tests unless requested
• Do not use external APIs beyond OpenAI (if needed)
• Do not add build tools or bundlers (no Webpack, Vite, etc.)