Skip to content

Commit d7fa1e7

Browse files
netbarrosnetbarros
committed
design
1 parent 73acfad commit d7fa1e7

7 files changed

Lines changed: 2128 additions & 1 deletion

File tree

‎.cursor/rules/cursor-rules-quantum.mdc‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ Você está auxiliando no desenvolvimento do **Quantum Project**, uma plataforma
1212
- `BLUEPRINT_V2.md` → design system, tokens, animações, arquitetura
1313
- `AGENTS.md` → convenções, padrões, anti-patterns
1414
- `SDD.md` → schema, API contracts, tipos
15-
15+
docs\PR-COMPLETE-COMPLEMENT-PR00.md
16+
docs\PR-00.md
1617
---
1718

1819
## REGRAS DE GERAÇÃO

‎.vscode/devocional.code-workspace‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"folders": [
3+
{
4+
"path": ".."
5+
}
6+
],
7+
"settings": {}
8+
}

‎CLAUDE.md‎

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
**Quantum Project** is a behavioral transformation SaaS platform powered by AI. It's a mobile-first PWA guiding users through a 365-day identity evolution journey.
8+
9+
- **Frontend**: Next.js 16 (App Router), React 19, Tailwind CSS 4, Framer Motion
10+
- **Backend**: Express + TypeScript, Prisma ORM, PostgreSQL, Redis
11+
- **AI Layer**: OpenRouter gateway with Claude/GPT fallback chain
12+
- **Architecture**: 5-Agent Mesh (ContentAgent, PersonalizationAgent, ProgressAgent, NotificationAgent, MonetizationAgent)
13+
14+
---
15+
16+
## Commands
17+
18+
### Development (Full Stack)
19+
20+
```bash
21+
# Start all services (PostgreSQL + Redis + Backend + Frontend)
22+
docker-compose up -d
23+
24+
# Backend only
25+
cd backend && npm run dev # tsx watch mode on port 3001
26+
27+
# Frontend only
28+
cd frontend && npm run dev # Next.js dev server on port 3000
29+
```
30+
31+
### Database
32+
33+
```bash
34+
cd backend
35+
npx prisma migrate dev # Run migrations in dev mode
36+
npx prisma migrate deploy # Run migrations in production
37+
npx prisma generate # Generate Prisma client
38+
npx prisma studio # Open Prisma Studio GUI
39+
npm run prisma:seed # Seed database with initial data
40+
```
41+
42+
### Testing
43+
44+
```bash
45+
# Backend tests
46+
cd backend && npm test # Run Vitest once
47+
cd backend && npm run test:watch # Run Vitest in watch mode
48+
49+
# Frontend E2E
50+
cd frontend && npm run test:e2e # Playwright tests
51+
```
52+
53+
### Build & Deploy
54+
55+
```bash
56+
# Backend
57+
cd backend && npm run build # TypeScript compilation to dist/
58+
cd backend && npm start # Run compiled code
59+
60+
# Frontend
61+
cd frontend && npm run build # Next.js production build
62+
cd frontend && npm run lint # ESLint check
63+
```
64+
65+
---
66+
67+
## Architecture
68+
69+
### Monorepo Structure
70+
71+
```
72+
quantum-project/
73+
├── frontend/ # Next.js 16 PWA
74+
│ ├── src/app/ # App Router - route groups (auth), (protected)
75+
│ ├── src/components/ # UI components organized by domain
76+
│ ├── src/hooks/ # React Query hooks for data fetching
77+
│ ├── src/lib/ # Utilities (animations.ts, api.ts)
78+
│ └── src/stores/ # Zustand global state
79+
├── backend/ # Express API
80+
│ ├── src/agents/ # Agent system (BaseAgent, AgentRegistry)
81+
│ ├── src/controllers/ # Route handlers
82+
│ ├── src/middleware/ # Auth, rate limiting, validation
83+
│ ├── src/routes/ # API route definitions
84+
│ ├── src/services/ # AIGateway, TokenTracker, PushNotification
85+
│ └── prisma/ # Schema, migrations, seed.ts
86+
└── docs/ # BLUEPRINT.md, SDD.md, architecture diagrams
87+
```
88+
89+
### Agent System (PicoClaw v2)
90+
91+
All agents extend `BaseAgent` and communicate via `AgentRegistry`:
92+
93+
```typescript
94+
// BaseAgent.ts - Never call agents directly, always use registry
95+
abstract class BaseAgent {
96+
abstract execute(message: AgentMessage): Promise<AgentMessage>;
97+
async communicate(
98+
targetAgent: string,
99+
message: Omit<AgentMessage, "sourceAgent" | "timestamp">,
100+
);
101+
}
102+
103+
// AgentRegistry.ts - Singleton orchestrator
104+
AgentRegistry.getInstance().dispatch(message); // Route messages between agents
105+
AgentRegistry.getInstance().register(agent); // Register new agents
106+
```
107+
108+
**Agents**: ContentAgent (session generation), PersonalizationAgent (behavior analysis), ProgressAgent (consciousnessScore/levels), NotificationAgent (PWA push), MonetizationAgent (subscription enforcement).
109+
110+
### AI Gateway
111+
112+
OpenRouter integration with automatic fallback chain:
113+
114+
```typescript
115+
// AIGateway.ts - Always use this, never call OpenRouter directly
116+
AIGateway.generateContent(input); // Returns AIResponse with fallback to static content
117+
118+
// Fallback chain: Claude 3.5 Sonnet → GPT-4o-mini → Static Content
119+
```
120+
121+
### Frontend Data Flow
122+
123+
```
124+
Components → Hooks (React Query) → API Client → Backend API
125+
↓
126+
Zustand (auth, session state)
127+
```
128+
129+
- **React Query** for all server state - never `useEffect` + fetch
130+
- **Zustand** only for client state (auth, UI preferences)
131+
- Custom hooks in `src/hooks/` wrap all API calls
132+
133+
---
134+
135+
## Key Conventions
136+
137+
### System 6 Design System
138+
139+
**Colors**: Use CSS variables, never hardcoded hex
140+
141+
- Background: `--q-bg-depth` (#080810), `--q-bg-surface`, `--q-bg-raised`
142+
- Accent: `--q-accent-8` (primary), `--q-accent-9` (hover)
143+
- Text: `--q-text-primary`, `--q-text-secondary`, `--q-text-tertiary`
144+
145+
**Typography**:
146+
147+
- `font-[family-name:var(--font-instrument)]` - Content (headlines, affirmations, reflections)
148+
- `font-[family-name:var(--font-dm-sans)]` - UI elements, labels
149+
150+
**Animations**: Import from `lib/animations.ts`, never inline
151+
152+
```typescript
153+
import { VARIANTS, TRANSITIONS } from '@/lib/animations';
154+
155+
<motion.div variants={VARIANTS.cardReveal} transition={TRANSITIONS.spring} />
156+
```
157+
158+
**Button Pattern**: Always include `whileTap` and specific styling
159+
160+
```typescript
161+
<motion.button
162+
whileTap={{ scale: 0.97 }}
163+
whileHover={{ scale: 1.01 }}
164+
className="h-12 rounded-full bg-[var(--q-accent-8)] text-white"
165+
>
166+
```
167+
168+
### TypeScript Strict Rules
169+
170+
- No `any` type - ever
171+
- No `@ts-ignore` - use proper type guards
172+
- Explicit return types on all functions
173+
- All API responses typed via `src/types/`
174+
175+
### Backend Patterns
176+
177+
**Zod Validation**: All routes use Zod schemas via middleware
178+
**No Prisma in Middleware**: Controllers only
179+
**Error Handling**: Structured logger (no `console.log` in production)
180+
**JWT Auth**: Stateless tokens, validated in `auth.middleware.ts`
181+
182+
### API Client
183+
184+
```typescript
185+
// src/lib/api.ts - Centralized Axios instance with interceptors
186+
const api = axios.create({ baseURL: "/api" });
187+
api.interceptors.request.use((config) => {
188+
const token = useAuthStore.getState().token;
189+
if (token) config.headers.Authorization = `Bearer ${token}`;
190+
return config;
191+
});
192+
```
193+
194+
---
195+
196+
## Environment Setup
197+
198+
Copy and configure both `.env` files:
199+
200+
```bash
201+
# backend/.env
202+
DATABASE_URL="postgresql://quantum:password@localhost:5432/quantum_project"
203+
REDIS_URL="redis://:redispass@localhost:6379"
204+
JWT_SECRET="your-jwt-secret-min-32-chars"
205+
OPENROUTER_API_KEY="your-openrouter-key"
206+
VAPID_PUBLIC_KEY="web-push-public"
207+
VAPID_PRIVATE_KEY="web-push-private"
208+
209+
# frontend/.env
210+
NEXT_PUBLIC_API_URL="http://localhost:3001"
211+
```
212+
213+
---
214+
215+
## Route Groups
216+
217+
Frontend uses Next.js route groups for layout organization:
218+
219+
- `(auth)/` - Login, register (no navbar)
220+
- `(protected)/` - All authenticated pages (with Navbar)
221+
- `dashboard/`, `session/`, `profile/`, `settings/`, `admin/`
222+
223+
Backend route prefixes:
224+
225+
- `/api/auth/*` - Authentication
226+
- `/api/session/*` - Daily sessions
227+
- `/api/progress/*` - User progress/stats
228+
- `/api/admin/*` - Admin operations (requires ADMIN role)
229+
230+
---
231+
232+
## Documentation
233+
234+
Key docs in `docs/`:
235+
236+
- `BLUEPRINT.md` - Design system, tokens, animations
237+
- `SDD.md` - API contracts, types, architecture diagrams
238+
- `PHASES.md` - Roadmap and current status
239+
- `AGENTS.md` - Agent conventions
240+
- `QUANTUM_DESIGN_SYSTEM.md` - Complete design reference
241+
- `docs\PR-COMPLETE-COMPLEMENT-PR00.md`
242+
- `docs\PR-00.md`
243+
244+
Read these before making architectural changes.

‎backend/prisma/seed.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ async function main() {
1616
where: { email: 'system@quantumproject.app' },
1717
update: {
1818
password: hashedPassword,
19+
role: 'ADMIN',
1920
},
2021
create: {
2122
email: 'system@quantumproject.app',

0 commit comments

Comments
 (0)