Assetly

A full-stack asset management and network discovery platform for tracking, monitoring, and cataloging IT assets across your infrastructure.

Assetly automates network scanning to discover devices, tracks their interfaces and IP addresses, and maintains a detailed audit log of all changes over time.

Features

• Automated Network Discovery - Scan IP network ranges to discover and catalog assets automatically
• Asset Tracking - Track devices, network interfaces, MAC addresses, and IP assignments
• Change Auditing - Full audit log of all asset modifications (inserts, updates, deletes) with diff tracking
• Distributed Scanning - Celery-based worker architecture with RabbitMQ for scalable, parallel scanning
• Scheduled Scans - Cron-based scheduling for periodic network discovery
• API-First Design - Complete REST API with OpenAPI documentation and auto-generated TypeScript client
• User Management - Role-based access with JWT authentication and API key support for scanner workers

Tech Stack

Layer	Technologies
Backend	Python, FastAPI, SQLModel, PostgreSQL, Alembic
Frontend	TypeScript, React, Vite, Chakra UI, TanStack Router/Query
Task Queue	Celery, RabbitMQ
Infrastructure	Docker Compose, Traefik, GitHub Actions
Code Quality	Ruff, Mypy, Biome, Pre-commit hooks

Quick Start

Prerequisites

• Docker and Docker Compose
• uv (Python package manager)
• Node.js (managed via .nvmrc with fnm or nvm)

Running with Docker Compose

# Clone the repository
git clone <repo-url>
cd assetly

# Start the full stack with live reload
docker compose watch

The following services will be available:

Service	URL
Frontend	http://localhost:5173
Backend API	http://localhost:8000
API Docs (Swagger)	http://localhost:8000/docs
Adminer (DB UI)	http://localhost:8080
Traefik Dashboard	http://localhost:8090
MailCatcher	http://localhost:1080

Default superuser credentials are configured in the .env file.

Project Structure

assetly/
├── backend/                  # FastAPI application
│   ├── app/
│   │   ├── api/routes/       # API endpoint handlers
│   │   ├── models/           # SQLModel database models
│   │   ├── crud/             # Database CRUD operations
│   │   ├── services/         # Business logic
│   │   ├── workflows/        # Background job workflows
│   │   ├── audit/            # Change audit logging
│   │   ├── core/             # Config, DB, security, Celery setup
│   │   ├── alembic/          # Database migrations
│   │   └── tests/            # Pytest test suite
│   └── assetly_processor/    # Scanner processor worker module
├── frontend/                 # React + Vite application
│   ├── src/
│   │   ├── routes/           # TanStack Router pages
│   │   ├── components/       # React components
│   │   ├── client/           # Auto-generated OpenAPI client
│   │   └── hooks/            # Custom React hooks
│   └── tests/                # Playwright E2E tests
├── docker-compose.yml        # Main service definitions
├── docker-compose.override.yml  # Dev overrides (volumes, live reload)
├── docker-compose.traefik.yml   # Traefik reverse proxy config
├── scripts/                  # Utility scripts
└── .github/workflows/        # CI/CD pipelines

Development

Backend

cd backend
uv sync                        # Install dependencies
fastapi dev app/main.py        # Run dev server

# Testing
bash scripts/test.sh           # Run tests with coverage

# Linting & type checking
uv run ruff check --fix
uv run mypy app/

Frontend

cd frontend
fnm use                        # Set Node.js version
npm install                    # Install dependencies
npm run dev                    # Start Vite dev server

# Generate TypeScript client from OpenAPI spec
npm run generate-client

# Linting
npm run lint

# E2E tests (requires backend running)
npx playwright test

Database Migrations

docker compose exec backend bash
alembic revision --autogenerate -m "Description"
alembic upgrade head

Configuration

Configuration is managed through environment variables in the .env file. Key settings:

Variable	Description
DOMAIN	Base domain (localhost for dev)
FRONTEND_HOST	Frontend URL for CORS and email links
ENVIRONMENT	local, staging, or production
POSTGRES_*	PostgreSQL connection settings
SECRET_KEY	JWT signing secret
RABBITMQ_BROKER_*	RabbitMQ connection settings
SMTP_*	Email server configuration
SENTRY_DSN	Sentry error tracking (optional)
TIMEZONE	Application timezone

See the .env file for the complete list of configurable options.

License

This project is licensed under the MIT License - see the LICENSE file for details.