152 lines
5 KiB
Markdown
152 lines
5 KiB
Markdown
# Project Overview
|
|
|
|
**Name**: Veridian Cultivation Platform
|
|
**Type**: Full-stack SaaS application (backend + frontend)
|
|
**Primary Languages**: TypeScript (Node.js 20, React 18)
|
|
**Status**: v0.1.0, Internal Testing
|
|
|
|
## High-Level Description
|
|
|
|
Veridian is a cultivation management platform for licensed cannabis facilities that centralizes:
|
|
- Grow Operations: Tasks, batches, rooms, and cultivation workflows
|
|
- Labor Tracking: Timeclock, hours, and cost-per-batch analysis
|
|
- Compliance: Document storage, audit packets, and METRC alignment
|
|
- Inventory: Materials, nutrients, and supplies with lot tracking
|
|
- Integrations: Environmental monitoring and hardware dashboards
|
|
- Communications: Task comments, announcements, and notifications
|
|
|
|
**External Systems**:
|
|
- PostgreSQL 15.x (primary database via Prisma ORM)
|
|
- METRC API (read-only in v1, California track-and-trace)
|
|
- SensorPush environmental sensors (via Veridian Edge agent)
|
|
- VPS deployment: nexus-vector
|
|
|
|
## Multi-Repo Architecture
|
|
|
|
This repo works in conjunction with **veridian-edge** as a single codebase:
|
|
- **veridian** (this repo): Main platform backend + frontend
|
|
- **veridian-edge**: SensorPush edge agent that polls SensorPush Cloud API and syncs environmental readings to Veridian backend
|
|
|
|
When making changes, consider the API contract between these two repos:
|
|
- Edge agent → Veridian backend API endpoints
|
|
- Data models must match between edge agent and backend
|
|
- Authentication/authorization patterns
|
|
|
|
## Layout
|
|
|
|
```
|
|
veridian/
|
|
├── backend/ # Express/Fastify backend API
|
|
│ ├── src/ # Source code
|
|
│ ├── prisma/ # Database schema and migrations
|
|
│ └── package.json # Node.js dependencies
|
|
├── frontend/ # React + Vite frontend
|
|
│ ├── src/ # Source code
|
|
│ └── package.json # Dependencies
|
|
├── docs/ # Architecture and compliance docs
|
|
├── specs/ # Feature specifications (Spec Kit workflow)
|
|
├── design-os/ # Design system components
|
|
└── docker-compose.yml # Local development stack
|
|
```
|
|
|
|
## Conventions
|
|
|
|
### Language/Style
|
|
- **TypeScript strict mode** enabled
|
|
- **ESLint + Prettier** for formatting
|
|
- **Prisma 5.x** for database access
|
|
- **Conventional commits** for git messages
|
|
|
|
### Package Manager
|
|
- **Use `bun` instead of `npm`** by default
|
|
- Commands: `bun install`, `bun run`, `bun test`, `bun add`
|
|
|
|
### Error Handling
|
|
- Throw semantic errors with clear messages
|
|
- Use Result types for operations that can fail
|
|
- Never expose sensitive data in error messages
|
|
|
|
### Logging
|
|
- Use structured logging (JSON in production)
|
|
- No `console.log` in production code
|
|
- Log levels: error, warn, info, debug
|
|
|
|
### Config
|
|
- Read from environment variables
|
|
- Never hard-code secrets or API keys
|
|
- Use `.env.example` as template
|
|
|
|
## Patterns & Playbooks
|
|
|
|
### How to Add New API Endpoints
|
|
1. Update Prisma schema if needed (`prisma/schema.prisma`)
|
|
2. Run migration: `bunx prisma migrate dev --name description`
|
|
3. Create route handler in `backend/src/routes/`
|
|
4. Add request validation (zod or similar)
|
|
5. Implement business logic in service layer
|
|
6. Add tests in `backend/src/__tests__/`
|
|
7. Update API documentation
|
|
|
|
### How to Add New Frontend Components
|
|
1. Create component in `frontend/src/components/`
|
|
2. Follow existing design system patterns (see `design-os/`)
|
|
3. Use TypeScript with proper prop types
|
|
4. Add responsive styles (Tailwind CSS)
|
|
5. Create tests if component has logic
|
|
6. Export from component index file
|
|
|
|
### How to Write Database Migrations
|
|
1. Modify `backend/prisma/schema.prisma`
|
|
2. Run `bunx prisma migrate dev --name description`
|
|
3. Generate client: `bunx prisma generate`
|
|
4. For production: `bunx prisma migrate deploy`
|
|
|
|
### How to Run Locally
|
|
**Backend:**
|
|
```bash
|
|
cd backend
|
|
bun install
|
|
cp .env.example .env # Configure DB connection
|
|
bunx prisma migrate dev
|
|
bun run dev
|
|
```
|
|
|
|
**Frontend:**
|
|
```bash
|
|
cd frontend
|
|
bun install
|
|
cp .env.example .env # Configure API URL
|
|
bun run dev
|
|
```
|
|
|
|
**Full Stack (Docker):**
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
### Important Environment Variables
|
|
- `DATABASE_URL`: PostgreSQL connection string
|
|
- `JWT_SECRET`: Secret for JWT token signing
|
|
- `METRC_API_KEY`: METRC integration (read-only)
|
|
- `SENSORPUSH_WEBHOOK_SECRET`: Webhook verification for edge agent
|
|
|
|
## PR & Learning Workflow
|
|
|
|
- When a PR introduces a new pattern or fixes a subtle issue:
|
|
1. Summarize the lesson in 1-2 bullets
|
|
2. Append under "Patterns & Playbooks" above
|
|
3. Consider updating relevant documentation in `docs/`
|
|
|
|
## Testing Strategy
|
|
|
|
- **Unit tests**: Jest for pure functions and business logic
|
|
- **Integration tests**: API endpoint tests with test database
|
|
- **E2E tests**: Browser tests for critical flows (login, batch creation)
|
|
- **VPS verification**: After deployment, verify on nexus-vector
|
|
|
|
## Compliance Notes
|
|
|
|
- **METRC is system of record** for California track-and-trace
|
|
- All compliance-relevant changes must be documented
|
|
- Audit logs must capture: who, what, when, for critical operations
|
|
- See `docs/compliance-notes-ca.md` for detailed guidance
|