Imported from armaan-are/Stockzeo (AGENTS.md). Install upstream with npx skills add armaan-are/Stockzeo. Copyright stays with the author.

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.

We are building Stockzeo. Simple fintech style app with a Supabase backend and a React frontend. Plan to use React Native later to port to mobile.

Core Features:

Authentication:

• User signup/login/logout
• Persistent sessions
• Protected dashboard routes
• Password reset

Portfolio System:

• Every user starts with a virtual cash balance (default: $1,000)
• Track total portfolio value
• Track unrealized and realized gains/losses
• Display holdings and allocation

Trading Engine:

• Buy and sell stocks using paper money
• Market order execution only for MVP
• Validate sufficient funds before purchases
• Validate sufficient share ownership before selling
• Server-side trade validation
• Maintain transaction history

Market Data:

• Search stocks by ticker or company name
• Fetch real-time or delayed stock prices from an external market API
• Show price movement and percentage change
• Basic historical chart support
• Trending stocks section

Dashboard:

• Portfolio balance card
• Holdings overview
• Daily portfolio performance
• Recent trades

Asset Detail Pages:

• Stock symbol and company info
• Price chart
• Buy/sell controls
• User position summary
• Current holdings information

System Architecture:

• Frontend: Next.js + TypeScript + Tailwind CSS
• Mobile later via React Native
• Backend/database/authentication via Supabase
• Use PostgreSQL database
• API routes handle all trading logic
• Frontend never directly trusted for trade prices
• Server independently fetches current prices before executing trades

Database Entities:

• users
• portfolios
• portfolio_history
• holdings
• trades
• achievements
• user_achievements

Current Supabase Database Contract:

• Supabase Auth is the identity source. App-owned rows must be scoped to auth.users.id.
• All per-user application tables use user_id uuid references auth.users(id) on delete cascade, except the existing users profile table, which uses auth_user_id uuid references auth.users(id) on delete cascade.
• users.id may remain a generated int8 row id, but never use it for authorization. Use users.auth_user_id = auth.uid().
• The existing profile table uses exact column names "First Name" and "Last Name"; quote these names in SQL and Supabase selects.
• New signup initializes users, portfolios, and a first portfolio_history point. Zero-state tables such as holdings and trades should usually have no rows until real activity occurs.
• Any future trading engine that changes portfolio value should also insert or update a portfolio_history snapshot for the current date so the balance chart stays database-backed over time.

Required tables and fields:

• users
  • id int8 generated by default as identity primary key
  • auth_user_id uuid unique references auth.users(id) on delete cascade
  • created_at timestamptz default now()
  • "First Name" text
  • "Last Name" text
  • email text
  • age int8
  • role text default 'user'
• portfolios
  • id int8 generated by default as identity primary key
  • user_id uuid unique references auth.users(id) on delete cascade
• cash_balance numeric(14,2) default 1000
• starting_balance numeric(14,2) default 1000
• total_value numeric(14,2) default 0
• daily_change_amount numeric(14,2) default 0
• daily_change_percent numeric(8,4) default 0
• unrealized_gain_loss numeric(14,2) default 0
• realized_gain_loss numeric(14,2) default 0
• created_at timestamptz default now()
• updated_at timestamptz default now()
• portfolio_history
  • id int8 generated by default as identity primary key
  • user_id uuid references auth.users(id) on delete cascade
  • recorded_on date default current_date
  • total_value numeric(14,2) default 0
  • cash_balance numeric(14,2) default 0
  • created_at timestamptz default now()
  • unique constraint on (user_id, recorded_on)
• holdings
  • id int8 generated by default as identity primary key
  • user_id uuid references auth.users(id) on delete cascade
  • symbol text
  • company_name text
  • quantity numeric(18,6) default 0
  • average_cost numeric(14,4) default 0
  • current_price numeric(14,4) default 0
  • daily_change_percent numeric(8,4) default 0
  • created_at timestamptz default now()
  • updated_at timestamptz default now()
• trades
  • id int8 generated by default as identity primary key
  • user_id uuid references auth.users(id) on delete cascade
  • symbol text
  • side text (buy or sell)
  • quantity numeric(18,6)
  • price numeric(14,4)
  • total_amount numeric(14,2)
  • created_at timestamptz default now()
• achievements
  • id int8 generated by default as identity primary key
  • name text
  • description text
  • icon text
  • display_order int8 default 0
  • created_at timestamptz default now()
• user_achievements
  • id int8 generated by default as identity primary key
  • user_id uuid references auth.users(id) on delete cascade
  • achievement_id int8 references achievements(id) on delete cascade
  • achieved_at timestamptz default now()
  • unique constraint on (user_id, achievement_id)

Required Row Level Security:

• Enable RLS on all public app tables.
• For users, authenticated users can manage only rows where auth_user_id = auth.uid().
• For portfolios, portfolio_history, holdings, trades, and user_achievements, authenticated users can manage only rows where user_id = auth.uid().
• For achievements, authenticated users can read definitions. Writes should be service/admin only.

Design Goals:

• Minimal and modern fintech aesthetic
• Fast loading
• Responsive/mobile-first
• Smooth transitions and animations
• Avoid clutter and overly dense financial UIs

Security Rules:

• Users can only access their own data
• Use row-level security
• Never trust frontend-submitted stock prices
• Authentication required for all portfolio/trading operations

Excluded From MVP:

• Options trading
• Crypto trading
• Social feeds
• Copy trading
• AI recommendations
• Competitions
• Native mobile app
• Advanced technical indicators
• Websocket streaming

Development Priorities:

1. Authentication
2. Dashboard shell
3. Database schema
4. Trading engine
5. Portfolio calculations
6. UI polish
7. Deployment

The app should be built incrementally with small scoped tasks suitable for agentic coding tools.