# Project Structure & Conventions

## Directory Layout

```
cve-dashboard/
├── backend/                    # Express API server
│   ├── server.js               # Main entry point — app setup, middleware, CVE/document routes inline
│   ├── setup.js                # One-time DB init + default admin creation
│   ├── cve_database.db         # SQLite database (gitignored)
│   ├── uploads/                # File storage (gitignored)
│   ├── routes/                 # Express route modules (factory pattern)
│   │   ├── auth.js
│   │   ├── users.js
│   │   ├── auditLog.js
│   │   ├── nvdLookup.js
│   │   ├── knowledgeBase.js
│   │   ├── archerTickets.js
│   │   ├── ivantiWorkflows.js
│   │   ├── ivantiFindings.js
│   │   ├── ivantiTodoQueue.js
│   │   └── compliance.js
│   ├── middleware/
│   │   └── auth.js             # requireAuth(db), requireRole(...roles)
│   ├── helpers/
│   │   └── auditLog.js         # logAudit() — fire-and-forget DB insert
│   ├── migrations/             # Sequential migration scripts (run manually with node)
│   └── scripts/                # Python utilities (compliance parsing, CSV import)
│
├── frontend/                   # React 19 SPA (Create React App)
│   └── src/
│       ├── App.js              # Main dashboard — CVE list, filters, modals, inline styles
│       ├── App.css             # Global styles and CSS variables
│       ├── contexts/
│       │   └── AuthContext.js  # Auth state provider (login, logout, role helpers)
│       └── components/
│           ├── LoginForm.js
│           ├── NavDrawer.js
│           ├── UserMenu.js
│           ├── CalendarWidget.js
│           ├── UserManagement.js
│           ├── AuditLog.js
│           ├── NvdSyncModal.js
│           ├── KnowledgeBaseModal.js
│           ├── KnowledgeBaseViewer.js
│           └── pages/          # Full-page views
│               ├── ReportingPage.js
│               ├── CompliancePage.js
│               ├── ComplianceUploadModal.js
│               ├── ComplianceDetailPanel.js
│               ├── ComplianceChartsPanel.js
│               ├── IvantiCountsChart.js
│               ├── KnowledgeBasePage.js
│               └── ExportsPage.js
│
├── docs/                       # Internal documentation (markdown)
├── start-servers.sh            # Start both servers in background
├── stop-servers.sh             # Stop both servers
└── DESIGN_SYSTEM.md            # UI design system reference (colors, typography, components)
```

## Backend Conventions

- Route modules export a factory function: `function createXxxRouter(db, ...middleware)` that returns an Express Router.
- The `db` (sqlite3 Database instance) is passed via dependency injection from `server.js`.
- Auth middleware: `requireAuth(db)` validates session cookie, attaches `req.user`. `requireRole('editor', 'admin')` checks role.
- All state-changing actions call `logAudit(db, { userId, username, action, entityType, entityId, details, ipAddress })`.
- Input validation is done inline in route handlers with early-return error responses.
- SQLite queries use the callback-based `db.run()`, `db.get()`, `db.all()` API.
- API routes are prefixed with `/api`. All endpoints except login/logout require a valid session cookie.
- CVE and document routes are defined inline in `server.js`; feature routes are in separate modules under `routes/`.

## Frontend Conventions

- Single-page app with page-level navigation managed in `App.js` (no React Router).
- Auth state managed via React Context (`AuthContext`). Use `useAuth()` hook for login/logout/role checks.
- API calls use `fetch()` with `credentials: 'include'` for cookie-based auth.
- API base URL from `process.env.REACT_APP_API_BASE`.
- Styling uses a mix of inline style objects (defined as constants in component files) and `App.css` global styles.
- Dark theme with a "tactical intelligence" aesthetic — see `DESIGN_SYSTEM.md` for color palette, typography, and component specs.
- Icons from `lucide-react`. Charts from `recharts`.
- Page components live in `components/pages/`. Shared components live in `components/`.
- No TypeScript — the project uses plain JavaScript throughout.