> ## Documentation Index
> Fetch the complete documentation index at: https://psys.alexcgomez.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> How to contribute to psys development

Thank you for considering contributing to psys! This guide will help you set up your development environment and understand the project structure.

## Development Setup

### Prerequisites

<CardGroup cols={2}>
  <Card title="Operating System" icon="linux">
    Linux with `ss` command (from `iproute2` package)
  </Card>

  <Card title="Runtime" icon="node-js">
    Node.js 18+ and npm
  </Card>

  <Card title="Optional" icon="docker">
    Docker for container detection features
  </Card>

  <Card title="Access" icon="shield">
    `/proc` filesystem access for process info
  </Card>
</CardGroup>

### Installation

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/alexcgomez/psys.git
    cd psys
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    npm install
    ```

    This will install all required dependencies including:

    * Next.js 15
    * React 19
    * TypeScript 5
    * Tailwind CSS
    * shadcn/ui components
    * React Flow
  </Step>

  <Step title="Start the development server">
    ```bash theme={null}
    npm run dev
    ```

    The app will be available at [http://localhost:3000](http://localhost:3000).
  </Step>

  <Step title="Verify it works">
    You should see your system's listening processes and connections in both the diagram and table views.
  </Step>
</Steps>

<Info>
  The development server uses Turbopack for fast hot-reloading. Changes to components will reflect instantly.
</Info>

## Project Structure

Understanding the codebase organization:

```
psys/
├── app/                      # Next.js App Router
│   ├── api/                  # API routes
│   │   └── connections/
│   │       ├── route.ts      # GET /api/connections
│   │       └── kill/
│   │           └── route.ts  # POST /api/connections/kill
│   ├── layout.tsx            # Root layout
│   ├── page.tsx              # Home page
│   └── globals.css           # Global styles
├── components/               # React components
│   ├── connections-dashboard.tsx  # Main dashboard
│   ├── process-icon.tsx      # Process icon component
│   ├── docker-icon.tsx       # Docker icon component
│   └── ui/                   # shadcn/ui components
│       ├── badge.tsx
│       ├── button.tsx
│       ├── card.tsx
│       ├── table.tsx
│       ├── tabs.tsx
│       └── svgs/             # Service logo SVGs
├── lib/                      # Core logic
│   ├── connections.ts        # Data collection from ss/proc
│   └── utils.ts              # Utilities (cn for classNames)
├── next.config.ts            # Next.js config
├── tailwind.config.ts        # Tailwind config
├── tsconfig.json             # TypeScript config
└── package.json              # Dependencies & scripts
```

## Code Conventions

### TypeScript

* **Strict mode enabled**: All code must pass TypeScript strict checks
* **Type safety**: Use explicit types for function parameters and return values
* **No any**: Avoid `any` type; use `unknown` or proper types
* **Exports**: Use named exports for utilities, default export for components

**Example:**

```typescript theme={null}
// Good
export function getProcessName(pid: number): string {
  // implementation
}

// Avoid
export function getProcessName(pid: any) {
  // implementation
}
```

### React Components

* **Client components**: Use `"use client"` directive when needed (hooks, events)
* **Props types**: Define inline types or use TypeScript interfaces
* **Hooks**: Follow React hooks rules (eslint-plugin-react-hooks enforces this)
* **File naming**: `kebab-case.tsx` for components

**Example:**

```tsx theme={null}
"use client";

import { useState } from "react";

type MyComponentProps = {
  title: string;
  count?: number;
};

export function MyComponent({ title, count = 0 }: MyComponentProps) {
  const [value, setValue] = useState(count);
  // implementation
}
```

### Styling

* **Tailwind CSS**: Use utility classes for all styling
* **cn utility**: Use `cn()` from `lib/utils.ts` to merge classNames
* **Responsive**: Add responsive breakpoints (`md:`, `lg:`) where appropriate
* **Dark mode**: Use CSS variables from `globals.css` (e.g., `text-foreground`)

**Example:**

```tsx theme={null}
import { cn } from "@/lib/utils";

<div className={cn(
  "rounded-lg border-2 bg-card",
  isActive && "border-primary",
  className
)}>
  {children}
</div>
```

### Data Collection

* **Error handling**: Always wrap shell commands in try-catch
* **Parsing**: Use regex for parsing `ss` output (see `lib/connections.ts:35-36`)
* **Normalization**: Normalize addresses and ports consistently
* **Performance**: Cache Docker lookups when possible

**Example:**

```typescript theme={null}
try {
  const output = execSync("ss -tlnp 2>/dev/null", { encoding: "utf8" });
  // parse output
} catch {
  // handle gracefully - don't crash the app
  return { listeners: [], connections: [] };
}
```

## Testing

<Warning>
  psys currently does not have automated tests. Adding test coverage would be a valuable contribution!
</Warning>

### Manual Testing Checklist

When making changes, verify:

* [ ] Listeners are displayed correctly in both diagram and table views
* [ ] Connections are drawn properly between nodes
* [ ] Process icons match the detected service (Node.js, Redis, etc.)
* [ ] Docker containers are labeled with the container name
* [ ] Table sorting and filtering work as expected
* [ ] Kill process button sends correct PID to API
* [ ] Error states are handled gracefully (e.g., `ss` not available)
* [ ] Page auto-refreshes every 5 seconds
* [ ] No console errors in browser DevTools

### Testing with Docker

To test Docker container detection:

```bash theme={null}
# Start a Redis container
docker run -d -p 6379:6379 --name test-redis redis

# Start a PostgreSQL container
docker run -d -p 5432:5432 --name test-postgres \
  -e POSTGRES_PASSWORD=postgres postgres

# Verify they appear in psys with Docker icons
```

## Pull Request Guidelines

### Before Submitting

<Steps>
  <Step title="Create a feature branch">
    ```bash theme={null}
    git checkout -b feature/my-new-feature
    ```
  </Step>

  <Step title="Make your changes">
    Follow the code conventions above and test thoroughly.
  </Step>

  <Step title="Lint your code">
    ```bash theme={null}
    npm run lint
    ```

    Fix any linting errors before committing.
  </Step>

  <Step title="Build the project">
    ```bash theme={null}
    npm run build
    ```

    Ensure there are no build errors.
  </Step>

  <Step title="Test in production mode">
    ```bash theme={null}
    npm start
    ```

    Verify your changes work in production mode (optimizations enabled).
  </Step>
</Steps>

### Commit Messages

Use clear, descriptive commit messages:

* **Format**: `<type>: <description>`
* **Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`

**Examples:**

```
feat: add support for UDP connections
fix: handle IPv6 addresses correctly
docs: update architecture diagram
refactor: simplify address parsing logic
```

### Pull Request Template

When opening a PR, include:

1. **Description**: What does this PR do?
2. **Motivation**: Why is this change needed?
3. **Testing**: How did you test this?
4. **Screenshots**: (if UI changes) Before/after screenshots
5. **Breaking changes**: Does this break existing functionality?

**Example:**

```markdown theme={null}
## Description
Adds support for filtering listeners by process name.

## Motivation
Users with many processes need a way to quickly find specific services.

## Testing
- Tested with 50+ listeners
- Verified filtering works in both diagram and table views
- No performance regressions observed

## Screenshots
[Attach screenshot of filter UI]
```

## Common Contribution Ideas

<CardGroup cols={2}>
  <Card title="Features" icon="sparkles">
    * Support for UDP connections
    * Process filtering and search
    * Export data as JSON/CSV
    * Historical connection tracking
  </Card>

  <Card title="Tests" icon="vial">
    * Unit tests for parsing logic
    * Integration tests for API routes
    * E2E tests with Playwright
  </Card>

  <Card title="Documentation" icon="book">
    * Add JSDoc comments
    * Create video tutorials
    * Write troubleshooting guide
  </Card>

  <Card title="Performance" icon="gauge">
    * Optimize React Flow rendering
    * Reduce polling frequency options
    * Memoize expensive computations
  </Card>
</CardGroup>

## Getting Help

* **Issues**: [github.com/alexcgomez/psys/issues](https://github.com/alexcgomez/psys/issues)
* **Discussions**: Use GitHub Discussions for questions
* **Code review**: Maintainers will review PRs and provide feedback

<Tip>
  Start with small contributions like fixing typos or improving documentation. This helps you get familiar with the codebase and contribution process.
</Tip>

## Code of Conduct

Be respectful and constructive in all interactions. We're all here to build better software together.

* **Be kind**: Respect different perspectives and experience levels
* **Be helpful**: Share knowledge and help others learn
* **Be patient**: Reviews take time; maintainers are often volunteers
* **Be professional**: Keep discussions focused on the code and technical matters

## License

By contributing to psys, you agree that your contributions will be licensed under the same license as the project.