Imported from widescopeindustries/credit-repair-app (
AGENTS.md). Install upstream withnpx 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
typingmodule for complex types:List,Dict,Optional,Union - Use Pydantic for data validation and serialization
- Use
str, Enumfor 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
HTTPExceptionfor API errors (400, 404, 500 status codes) - Log errors appropriately (consider adding logging in future)
- Gracefully handle missing data (use
Optionaltypes, 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
BaseModelfor all data structures - Keep business logic in service layer, not in route handlers
API Design:
- Use Pydantic models for request/response bodies
- Use
Formfor form data,Filefor 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
constandlet, nevervar - Use arrow functions for callbacks and event handlers
- Use template literals for string interpolation
- Use
async/awaitfor all API calls - Use
fetchAPI 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
FormDatafor 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.pyshould be thin, delegate to services - Services contain business logic, can be reused
- Models define data contracts, used for validation
- Configuration centralized in
config.pyviaSettingsclass - Data persisted locally (no database currently)
Configuration
- Environment variables in
.envfile (create from.env.example) - Settings managed via
pydantic-settingsinbackend/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
.envfile or sensitive data to git - Validate all file uploads (PDF only, file size limits)
Adding New Features
- Create/update Pydantic models in
models/schemas.py - Implement business logic in appropriate service file
- Add API endpoint in
api/main.py(or create new file) - Update frontend HTML/CSS/JS as needed
- Test manually via browser at http://localhost:8000
- 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.)
