An enterprise technology catalog built with Nuxt 4 and Neo4j graph database. Track technologies, versions, systems, teams, and policies in your organization with a graph-based data model.

Polaris helps organizations manage their technology landscape by:

• Technology Catalog: Track approved technologies and their versions
• Team-Specific Approvals: Different approval policies per team with version-specific controls
• System Inventory: Map systems and their technology dependencies
• Team Ownership: Link technologies and systems to responsible teams
• Policy Compliance: Define and track governance policies
• Dependency Visualization: Understand relationships through graph queries
• Audit Trail: Comprehensive tracking of all data changes for compliance and security

This project follows a 3-layer architecture pattern:

• Nuxt 4 Frontend: Modern Vue 3 application with server-side rendering
• Neo4j Graph Database: Stores relationships between technologies, systems, teams, and policies
• Standalone Migrations: Database schema managed via CLI tools
• 3-Layer API: Endpoints → Services → Repositories for clean separation of concerns

The server uses a consistent pattern across all 25 endpoints:

• Endpoints (server/api/) - HTTP request/response handling
• Services (server/services/) - Business logic and orchestration
• Repositories (server/repositories/) - Data access and query execution
• Queries (server/database/queries/) - Reusable Cypher query files

See docs/architecture/service-layer-pattern.md for detailed patterns.

polaris/ ├── app/ # Nuxt application │ ├── pages/ # Vue pages │ ├── components/ # Vue components │ └── app.vue # Root component ├── server/ # Server-side code (3-layer architecture) │ ├── api/ # API endpoints (HTTP layer) │ ├── services/ # Business logic layer │ ├── repositories/ # Data access layer │ ├── utils/ # Server utilities and validators │ └── database/queries/ # Cypher query files ├── schema/ # Database management │ ├── migrations/ # Cypher migration files │ ├── scripts/ # Migration CLI tools │ └── fixtures/ # Test data ├── test/ # Test files (layered testing strategy) │ ├── server/ # Backend unit tests │ │ ├── api/ # API endpoint tests (mock services) │ │ ├── services/ # Service layer tests (mock repositories) │ │ ├── repositories/ # Repository tests (real database) │ │ └── utils/ # Utility unit tests │ ├── app/ # Frontend tests │ │ ├── e2e/ # End-to-end UI tests (Playwright) │ │ ├── components/ # Component tests │ │ ├── composables/ # Composable tests │ │ └── pages/ # Page tests │ ├── integration/ # Backend integration tests (cross-layer) │ ├── schema/ # Database schema tests │ ├── fixtures/ # Shared test helpers │ └── setup/ # Global test setup/teardown ├── content/ # In-app documentation (Markdown) │ ├── features/ # Feature documentation │ ├── architecture/ # Architecture guides │ └── api/ # API documentation ├── docs/ # Project documentation │ ├── architecture/ # Architecture decision records │ └── testing/ # Testing guides ├── public/ # Static assets ├── .github/ # GitHub Actions workflows ├── .devcontainer/ # Dev container configuration └── .ona/ # Gitpod automations 

• Node.js 18+ (LTS recommended)
• Docker and Docker Compose

# Clone the repository git clone https://github.com/localgod/polaris.git cd polaris # Install dependencies npm install # Start Neo4j (if not using dev container) cd .devcontainer && docker compose up -d neo4j && cd .. # Run database migrations npm run migrate:up # Start development server npm run dev

Visit http://localhost:3000 - the home page displays a real-time database status indicator.

For detailed setup instructions, see the Contributing Guide.

The project uses Neo4j 5 Community Edition with a standalone migration system.

# Check migration status npm run migrate:status # Apply pending migrations npm run migrate:up # Create new migration npm run migrate:create <name> # Seed database with sample data npm run seed # Seed database from GitHub repositories (generates real SBOMs) npm run seed:github # Technical users and API tokens are managed via the UI (/users) by superusers

For detailed database documentation, see the Contributing Guide.

For GitHub seeding, see Seeding from GitHub Repositories.

Polaris provides comprehensive OpenAPI 3.1 documentation for all REST API endpoints.

• Integrated UI: Visit /api-reference in the app for a fully integrated API reference
• Standalone UI: Visit /api-docs.html for a standalone interactive API reference powered by Scalar
• OpenAPI Spec: Download the raw OpenAPI specification at /openapi.json

The API documentation includes:

• Health: Health check and status endpoints
• Systems: System management and CRUD operations
• Components: Component catalog and dependency tracking
• Technologies: Technology catalog with version management
• Teams: Team management and ownership
• Policies: Policy and compliance management
• Repositories: Source code repository tracking
• Users: User management (admin only)

All endpoints include:

• Request/response schemas
• Parameter descriptions
• Example payloads
• Authentication requirements
• Error responses

When you add or modify API endpoints, regenerate the OpenAPI spec:

# Generate static OpenAPI spec node -e "import('./server/openapi.ts').then(m => require('fs').writeFileSync('public/openapi.json', JSON.stringify(m.openapiSpec, null, 2)))"

The spec is automatically generated from JSDoc comments in the API endpoint files.

All runnable scripts are defined in package.json. To see the full list of available scripts, run:

# List available npm scripts npm run

Run the specific script name shown in package.json to execute a task (for example, the repository includes scripts for development, database, testing, and linting).

The project supports multiple development environments:

• Dev Containers: Fully configured environment with Neo4j
• Gitpod: Cloud-based development with automations
• Local: Manual setup with Docker Compose

See Dev Container README and Gitpod Automations for details.

This project uses Vitest with a three-layer testing strategy. Available test scripts are defined in package.json; run npm run to list scripts and execute the desired script by name.

For detailed testing information, see:

• Testing Documentation - Complete testing guide
• Contributing Guide - How to write tests

Polaris uses Gartner's TIME framework for technology portfolio management with team-specific policies:

• TIME Categories: Tolerate, Invest, Migrate, Eliminate
• Per-Team Policies: Each team can have different TIME categories for the same technology
• Version-Specific Approvals: Categorize specific versions independently
• Approval Hierarchy: Version-specific > Technology-level > Default (eliminate)
• Rich Metadata: EOL dates, migration targets, version constraints, approval history

TIME Categories:

• 🟢 Invest: Strategic technologies worth continued investment
• 🔵 Migrate: Technologies to move to newer platforms
• 🟡 Tolerate: Keep running but minimize investment
• 🔴 Eliminate: Phase out and decommission

Example Use Case: Angular marked as "Migrate" for Frontend Team (EOL: 2025-12-31, target: React), while React is "Invest".

Documentation:

• TIME Framework Guide
• Implementation Summary
• Schema Design

API Endpoints:

• GET /api/technologies - List technologies with TIME categories
• GET /api/technologies/{name} - Technology details with approvals
• GET /api/teams/{name}/approvals - All approvals for a team
• GET /api/approvals/check - Check TIME category with hierarchy resolution

Polaris collects and tracks Software Bill of Materials (SBOM) from your CI/CD pipelines:

Workflow:

1. Register Repository: Link repository to a system

   POST /api/systems/my-system/repositories { "url": "https://github.com/org/repo" }

2. Submit SBOM: CI/CD submits SBOM after build

   POST /api/sboms { "repositoryUrl": "https://github.com/org/repo", "sbom": { /* CycloneDX or SPDX */ } }

Features:

• ✅ Supports CycloneDX and SPDX formats
• ✅ Automatic component extraction and deduplication
• ✅ Links components to systems for governance
• ✅ Tracks last SBOM scan timestamp
• ✅ Strict enforcement: repository must be registered first

Note: Polaris focuses on SBOM collection and component tracking. For vulnerability scanning, use complementary tools like GitHub Dependabot, Trivy, or Grype alongside Polaris.

Documentation:

• SBOM Schema Design
• ADR-0004: Exclude CVE Management

Polaris tracks all data changes with complete context for compliance, security, and debugging:

• Complete History: Every create, update, delete, and approval operation is logged
• User Accountability: Know who made each change and when
• Field-Level Tracking: See exactly what changed with before/after values
• Compliance Ready: Support for SOC 2, GDPR, HIPAA, PCI DSS requirements
• Security Monitoring: Detect unauthorized access and suspicious activities
• Rich Context: Capture IP address, session, reason, and metadata

What Gets Audited:

• CRUD operations on all entities (Technology, System, Team, Policy, Component, User)
• Approval operations with TIME framework decisions
• SBOM uploads and component tracking
• Relationship changes (ownership, stewardship)
• User activities (login, role changes)

Example Use Case: Track who approved React for the Frontend Team on 2025-11-05, why it was changed from "tolerate" to "invest", and what the previous approval settings were.

Documentation:

• Audit Trail Guide
• Schema Documentation
• Example Queries

API Endpoints:

• GET /api/audit/entity/{type}/{id} - Get audit trail for specific entity
• GET /api/audit/user/{userId} - Get all actions by a user
• GET /api/audit - Query audit logs with filters (operation, date range, source)

Available test scripts (by name) are defined in package.json. Run npm run to list scripts and then run the desired script by name. For example:

# List scripts npm run # Run the script shown in package.json, e.g.: # npm run <script-name>

Tests run in parallel in GitHub Actions:

• 4 parallel jobs: model, api, ui, smoke
• ~60% faster than sequential execution
• Layer-specific failures for better debugging
• Coverage reporting per layer with merged results

For testing guidelines and examples, see the Contributing Guide.

• Contributing Guide - Complete guide for contributors including setup, workflow, testing, and database management
• Dev Container Setup - Development container configuration
• Gitpod Automations - Automation configuration for cloud development
• Code of Conduct - Community guidelines
• Agent Instructions - Guidelines for AI agents working on this project

Polaris includes comprehensive in-app documentation powered by @nuxt/content:

• Getting Started: Installation and setup guides
• Features: TIME Framework, Team Approvals
• Architecture: Graph Model, Schema Design
• API: Endpoint documentation with examples

Access the documentation at /docs when running the application, or browse the content/ directory.

• Frontend: Nuxt 4, Vue 3, TypeScript, Tailwind CSS
• Database: Neo4j 5 Community Edition (graph database)
• Documentation: @nuxt/content with Markdown
• Testing: Vitest with Gherkin-style BDD
• Development: Docker, Dev Containers, Gitpod
• CI/CD: GitHub Actions with automated testing and coverage

• Graph-Based Data Model: Leverage Neo4j's native graph capabilities for complex relationships
• Type-Safe: Full TypeScript support throughout the stack
• Modern Frontend: Nuxt 4 with Vue 3 Composition API
• In-App Documentation: Comprehensive guides powered by @nuxt/content
• Standalone Migrations: Database schema managed independently via CLI
• Comprehensive Testing: Gherkin-style tests for better documentation
• Developer Experience: Dev containers and automations for quick setup

See LICENSE.md for details.