CivicLedger CLAUDE.md Instructions

Provides guidance for working with the CivicLedger codebase, a secure document management system built for US Government/Defense compliance.

What This Skill Does

When working in the CivicLedger repository, you will follow security-first development practices, maintain immutable audit logs, implement proper RBAC controls, and ensure all documentation stays current.

Project Context

**System:** Secure document management for FedRAMP/NIST 800-53 compliance

**Backend:** Spring Boot 3.3.0 + PostgreSQL

**Frontend:** Next.js 14+ with TypeScript and TailwindCSS

**Security:** AES-256-GCM encryption, SHA-256 hashing, immutable audit logs

Instructions

1. Security Requirements

**Before any file storage operation:**

Encrypt files using AES-256-GCM before storage

Calculate SHA-256 hash for document integrity

Generate and store encryption initialization vector (IV)

Record all operations in immutable audit logs

**RBAC enforcement:**

ADMINISTRATOR: Full system access

OFFICER: Upload and read documents

AUDITOR: Read audit logs only

**Audit logging:**

Use `@Aspect` annotation for service layer audit interceptor

Log: `action_type`, `user_id`, `timestamp`, `ip_address`, `resource_id`

Audit logs are write-once, never modified

2. Architecture Patterns

**Backend (Spring Boot):**

Controllers: API layer only (no business logic)

Services: Business logic and encryption operations

Repositories: Data access layer

**Frontend (Next.js):**

Use App Router with TypeScript

Implement Server Components where applicable

Style with TailwindCSS (high-contrast for accessibility)

Ensure Section 508 / WCAG 2.1 AA compliance

**Key entities:**

`AuditLog`: Immutable logs with action type, user, timestamp, IP, resource ID

`Document`: File hash, encryption IV, version number, classification level

3. Development Commands

**Backend:**

```bash

Start database

docker-compose up -d

Build and run

mvn clean install

mvn spring-boot:run

Tests

mvn test

mvn test -Dtest=ClassName

mvn test -Dtest=ClassName#methodName

```

**Frontend:**

```bash

cd frontend

Development

npm install

npm run dev

Production

npm run build

npm start

Linting

npm run lint

```

4. Task Management

**Always create TODO.md files in the `docs/` directory** for any feature or fix work:

Break down complex tasks into actionable items

Mark items as completed as you finish them

Keep task files organized in `docs/`

5. Documentation Maintenance

**Keep documentation in sync with code changes:**

Update relevant docs in `docs/` directory when making changes

Document new features, APIs, and architectural decisions

Keep API documentation aligned with implementation

Update README and guides when workflows change

6. Reference Documents

`DEVELOPMENT_PLAN.md`: Implementation roadmap

`DEV_CHECKLIST.md`: Development checklist

`docs/`: Project documentation directory

Usage Examples

**Example 1: Implementing file upload**

1. Create TODO.md in `docs/` outlining upload flow steps

2. Implement encryption in service layer with `@Aspect` audit

3. Calculate SHA-256 hash before storage

4. Store encrypted file with IV and hash

5. Update API documentation with new endpoint

6. Write tests for encryption, hashing, and audit logging

**Example 2: Adding new RBAC role**

1. Document role permissions in `docs/`

2. Update security configuration

3. Add role checks to relevant controllers

4. Update audit logging to capture role-based actions

5. Write integration tests for role enforcement

Constraints

Never store unencrypted files

Never skip audit logging for any operation

Never modify existing audit log entries

Always use provided Maven/npm commands

Always maintain Section 508 / WCAG 2.1 AA compliance

Always update documentation when changing code

CivicLedger CLAUDE.md Instructions

CivicLedger CLAUDE.md Instructions

What This Skill Does

Project Context

Instructions

1. Security Requirements

2. Architecture Patterns

3. Development Commands

Start database

Build and run

Tests

Development

Production

Linting

4. Task Management

5. Documentation Maintenance

6. Reference Documents

Usage Examples

Constraints

Reviews (0)