LLC Manager

Quality & Security

CI/CD Status

Project Info

Author	Byron Williams
Created	2026-01-18
Repository	ByronWilliamsCPA/llc-manager

---

Overview

A web application for managing LLC entities, tracking compliance dates, ownership structures, and associated documentation.

This project provides:

• CRUD API for LLC entities with pagination, search, and filtering
• Production-ready FastAPI backend with async PostgreSQL
• React + TypeScript frontend
• Security-first development practices with SBOM, SLSA provenance, and supply chain hardening

Features

• High Quality: 80%+ test coverage enforced via CI
• Type Safe: Full type hints with BasedPyright strict mode
• Well Documented: Clear docstrings and full guides
• Developer Friendly: Pre-commit hooks, automated formatting, linting
• Security First: Dependency scanning, security analysis, SBOM generation

Quick Start

Prerequisites

• Python 3.12+
• UV for dependency management
• Node.js 20+ and npm (for frontend)
• Docker + Docker Compose (for local PostgreSQL)

Install UV:

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Installation

# Clone repository
git clone https://github.com/ByronWilliamsCPA/llc-manager.git
cd llc-manager

# Install dependencies (includes dev tools)
uv sync --all-extras

# Setup pre-commit hooks
uv run pre-commit install

Running the API

# Start PostgreSQL
docker-compose up -d db

# Apply migrations
uv run alembic upgrade head

# Start the API server
uv run uvicorn llc_manager.main:app --reload
# API available at http://localhost:8000
# Docs at http://localhost:8000/api/docs

Frontend Development

The frontend is a React + TypeScript application built with Vite.

Frontend Quick Start

cd frontend
npm install
npm run dev

Frontend runs at http://localhost:3000 with hot reload.

Available Scripts

Command	Description
npm run dev	Start dev server with HMR
npm run build	Build for production
npm run test	Run tests
npm run lint:fix	Lint and auto-fix
npm run typecheck	Run TypeScript type checking
npm run generate-client	Generate API client from OpenAPI

API Client Generation

Generate a type-safe TypeScript client from the FastAPI OpenAPI schema:

# Start backend first
uv run uvicorn llc_manager.main:app &

# Generate client
cd frontend && npm run generate-client

This creates typed API functions in frontend/src/client/.

Docker

# Full stack (API :8000, frontend :3000, PostgreSQL :5432)
docker-compose up -d

# Production image
docker build -t llc_manager .

Development

Setup Development Environment

# Install all dependencies including dev tools
uv sync --all-extras

# Setup pre-commit hooks
uv run pre-commit install

# Run the fast suite (default: skips slow + integration markers)
uv run pytest -v

# Run the full suite (override default marker filter)
uv run pytest -v -m ""

# Run with coverage
uv run pytest --cov-report=html

# Run all quality checks
uv run pre-commit run --all-files

Code Quality Standards

All code must meet these requirements:

• Formatting: Ruff (88 char limit)
• Linting: Ruff with PyStrict-aligned rules (see below)
• Type Checking: BasedPyright strict mode
• Testing: Pytest with 80%+ coverage
• Security: Bandit + dependency scanning
• Documentation: Docstrings on all public APIs

PyStrict-Aligned Ruff Configuration

This project uses PyStrict-aligned Ruff rules for stricter code quality enforcement beyond standard Python linting:

Rule	Category	Purpose
BLE	Blind except	Prevent bare except: clauses
EM	Error messages	Enforce descriptive error messages
SLF	Private access	Prevent access to private members
INP	Implicit packages	Require explicit __init__.py
ISC	Implicit concatenation	Prevent implicit string concatenation
PGH	Pygrep hooks	Advanced pattern-based checks
RSE	Raise statement	Proper exception raising
TID	Tidy imports	Clean import organization
YTT	sys.version	Safe version checking
FA	Future annotations	Modern annotation syntax
T10	Debugger	No debugger statements in production
G	Logging format	Safe logging string formatting

These rules catch bugs that standard linting misses and enforce production-quality code patterns.

Running Tests

# Run the fast suite (default: skips slow + integration markers)
uv run pytest -v

# Run the full suite (override default marker filter)
uv run pytest -v -m ""

# Run specific test file
uv run pytest tests/unit/test_health.py -v

# Run with coverage report
uv run pytest --cov-report=term-missing

# Run tests in parallel
uv run pytest -n auto

Individual Tool Commands

# Format code
uv run ruff format .

# Lint and auto-fix
uv run ruff check --fix .

# Type checking
uv run basedpyright src

# Security scanning
uv run bandit -r src

# Dependency vulnerabilities
uv run pip-audit

Project Structure

llc-manager/
├── src/llc_manager/
│   ├── main.py                        # FastAPI app factory
│   ├── core/
│   │   ├── config.py                  # Pydantic Settings (env: LLC_MANAGER_*)
│   │   ├── exceptions.py              # Exception hierarchy
│   │   ├── cache.py                   # Redis cache client
│   │   └── sentry.py                  # Sentry error tracking
│   ├── db/
│   │   ├── base.py                    # SQLAlchemy Base + mixins
│   │   └── session.py                 # Async engine + session dependency
│   ├── models/                        # SQLAlchemy ORM models
│   │   ├── entity.py                  # Core LLC entity
│   │   ├── owner.py                   # Ownership structure
│   │   ├── state_registration.py
│   │   ├── bank_account.py
│   │   ├── document.py
│   │   ├── tax_filing.py
│   │   ├── registered_agent.py
│   │   └── entity_relationship.py     # Parent/child entity graph
│   ├── schemas/                       # Pydantic request/response schemas
│   │   ├── base.py
│   │   └── entity.py, owner.py, ...
│   ├── api/
│   │   ├── health.py                  # Kubernetes probes
│   │   └── v1/endpoints/
│   │       └── entities.py            # CRUD endpoints
│   ├── middleware/
│   │   ├── correlation.py             # X-Correlation-ID propagation
│   │   └── security.py               # SSRF protection
│   └── utils/
│       ├── logging.py                 # Structlog with correlation ID
│       └── financial.py              # Decimal precision utilities
├── frontend/                          # React + TypeScript (Vite)
├── tests/
│   ├── unit/
│   └── integration/
├── docs/                              # MkDocs documentation
├── alembic/                           # Database migrations
├── pyproject.toml
└── docker-compose.yml

Documentation

• CONTRIBUTING.md: How to contribute to the project
• docs/planning/: Project planning documents
• docs/planning/adr/: Architecture Decision Records

Testing

Testing Policy

All new functionality must include tests:

• Unit tests: Test individual functions/classes
• Integration tests: Test component interactions
• Coverage: Maintain 80%+ coverage
• Markers: Use pytest markers (@pytest.mark.unit, @pytest.mark.integration)

Test Guidelines

# Run the fast suite (default: skips slow + integration markers)
uv run pytest -v

# Run the full suite (override default marker filter)
uv run pytest -v -m ""

# Run only unit tests
uv run pytest -v -m unit

# Run only integration tests
uv run pytest -v -m integration

# Run with coverage requirements
uv run pytest

Security

Security-First Development

• Validate all inputs
• Use secure defaults
• Scan dependencies regularly
• Report vulnerabilities responsibly

Reporting Security Issues

Please report security vulnerabilities to byron@williamscpa.com rather than using the public issue tracker.

See the ByronWilliamsCPA Security Policy for complete disclosure policy and response timelines.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for:

• Development setup
• Code quality standards
• Testing requirements
• Git workflow and commit conventions
• Pull request process

Quick Checklist Before Submitting PR

• Code follows style guide (Ruff format + lint)
• All tests pass with 80%+ coverage
• BasedPyright type checking passes
• Docstrings added for new public APIs
• CHANGELOG.md updated (if significant change)
• Commits follow conventional commit format

Versioning

This project uses Semantic Versioning:

• MAJOR version: Incompatible API changes
• MINOR version: Backwards-compatible functionality additions
• PATCH version: Backwards-compatible bug fixes

Current version: 0.1.0

Automated Releases with Semantic Release

This project uses python-semantic-release for automated versioning based on Conventional Commits.

How it works:

1. Commit messages determine version bumps:

   • fix: commits trigger a PATCH release (1.0.0 → 1.0.1)
   • feat: commits trigger a MINOR release (1.0.0 → 1.1.0)
   • BREAKING CHANGE: in commit body or ! after type triggers MAJOR release (1.0.0 → 2.0.0)

2. On merge to main:

   • Analyzes commits since last release
   • Determines appropriate version bump
   • Updates version in pyproject.toml
   • Generates/updates CHANGELOG.md
   • Creates Git tag and GitHub Release
   • Publishes to PyPI (if configured)

Commit message examples:

# Patch release (bug fix)
git commit -m "fix: resolve null pointer in data parser"

# Minor release (new feature)
git commit -m "feat: add CSV export functionality"

# Major release (breaking change)
git commit -m "feat!: redesign API for better ergonomics

BREAKING CHANGE: API has been redesigned for improved usability.
See migration guide in docs/migration/v2.0.0.md"

Configuration: See [tool.semantic_release] in pyproject.toml for settings.

License

MIT License - see LICENSE for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: byron@williamscpa.com

Acknowledgments

Thank you to all contributors and the open-source community!

---

Made with ❤️ by Byron Williams