magma-stocks
You are a senior software architect and technical writer. I am building a full-stack web application for a university project. The frontend must use **Next.js**, and the backend must use a **Python framework (FastAPI preferred)**. Your task is to generate **complete technical documentation and system design** for this project. Project name: **StockVision – Advanced Stock Market Analytics Platform** Project description: This is a dynamic stock market analytics platform where users can explore real-world stock market data, track portfolios, create watchlists, and access advanced analytics features. The application will integrate with external stock market APIs to fetch real-time and historical market data. The platform will also include **premium features that users can purchase through a checkout system**, which satisfies the requirement of having a checkout/payment feature. Tech stack requirements: Frontend: * Next.js (App Router) * React * TypeScript * Tailwind CSS * Shadcn UI * TanStack Query * Chart.js or TradingView charts Backend: * Python FastAPI * PostgreSQL database * SQLAlchemy ORM * JWT authentication * Redis caching (optional) External APIs: * Alpha Vantage or Finnhub stock market API Payment: * Stripe or Razorpay The system must include the following core features: Authentication * User signup * User login * JWT-based authentication * Password hashing Stock Listing * List popular or trending stocks * Search stocks by symbol or company name * Display stock price, change %, and basic information Stock Detail Page * Detailed stock information * Historical price charts * Technical indicators * Company details * Market news (optional) Watchlist * Users can save stocks to a watchlist * Add/remove stocks Portfolio Tracker * Users can simulate investments * Track profit/loss * View portfolio value Premium Features * Advanced indicators * Unlimited watchlists * Export stock data * Advanced analytics Pricing and Checkout * Pricing page showing free vs premium plans * Checkout page * Payment integration with Stripe or Razorpay * Subscription management Required Pages: * Home * Login * Signup * Stocks listing page * Stock detail page * Watchlist * Portfolio * Pricing * Checkout * User dashboard/profile Please generate the following documentation: 1. High-level system architecture 2. Complete project folder structure (frontend + backend) 3. Database schema and ER diagram 4. API design with endpoints 5. Authentication flow 6. Data flow between frontend, backend, and stock APIs 7. UI page structure 8. Component architecture for Next.js 9. Backend service architecture 10. Deployment architecture 11. Optional scalability improvements The documentation should be structured professionally as if it were a real production project.
Comments (0)
Sign in to leave a comment
Project Tasks20
Implement Subscription & Payment API
As a backend developer, I want to implement subscription management and payment processing API so that users can upgrade to Premium via Razorpay or Stripe. Endpoints: GET /api/pricing/plans, POST /api/checkout/create-order, POST /api/checkout/verify-payment, GET /api/subscription, DELETE /api/subscription. Handle webhook events from Razorpay/Stripe for payment confirmation. Update user role to Premium on successful payment. Store subscription details in PostgreSQL.
Implement Stock Data API Integration
As a backend developer, I want to integrate with Alpha Vantage or Finnhub stock market API so that the platform can serve real-time and historical stock data to the frontend. Implement FastAPI endpoints: GET /api/stocks/trending, GET /api/stocks/search?q=, GET /api/stocks/{symbol}, GET /api/stocks/{symbol}/history?range=. Add Redis caching layer (TTL 60s for live prices, TTL 1h for historical). Handle IST timezone normalization for all timestamps. Rate limit handling and fallback for API quota exhaustion.
Implement Watchlist Backend API
As a backend developer, I want to implement watchlist CRUD API endpoints so that users can save and manage their stock watchlists. Endpoints: GET /api/watchlist, POST /api/watchlist/stocks, DELETE /api/watchlist/stocks/{symbol}, POST /api/watchlist (premium: create new watchlist). Enforce free-user limit (1 watchlist, max 5 stocks) via RBAC middleware. JWT auth required on all endpoints.
Implement RBAC & User Management API
As a backend developer, I want to implement role-based access control and admin user management API so that admins can manage user roles and permissions. Endpoints: GET /api/admin/users, PUT /api/admin/users/{id}/role, DELETE /api/admin/users/{id}, GET /api/admin/subscriptions. Middleware to enforce role checks (Free, Premium, Admin) on protected endpoints. Admin-only route guards.
Implement Theme & Design System
As a frontend developer, I want to implement the global color theme, typography, design tokens, and layout structure so that all pages match the magma-stocks mock-design pages exactly. This includes: setting up Tailwind config with Deep Blue (#1E3A8A), Vibrant Orange (#F97316), Green (#10B981), Red (#EF4444), Dark mode base (#0A0F1E), glassmorphism utilities, animated gradient background system, and font (Inter). Remove any pages from the scaffold that are not part of the required page set (e.g. welcome page if not in designs). Ensure the animated time-of-day gradient, particle/star-field canvas layer, and micro-interaction utilities (pulse, glow, flip) are globally available. This task must be completed before all other page implementation tasks.
Build Landing Page
As a frontend developer, I want to implement the Landing page based on the existing JSX design (Landing v2) so that users can view the platform and navigate to Login or Signup. The page includes: NavBar with logo and CTAs, Hero section with animated gradient and 3D globe concept, LiveMarketTicker, GlobeExchanges, FeatureHighlights, HowItWorks (3-step onboarding flow), AnimatedDashboardPreview, PricingSnapshot, Testimonials, CallToAction, and Footer. All sections must be responsive (mobile-first). Design is already complete — implement pixel-perfect from JSX design.
Build Login Page
As a frontend developer, I want to implement the Login page based on the existing JSX design (Login v2) so that users can sign in securely. The page includes: frosted-glass login card, email/password fields, 'Remember Me' checkbox, 'Forgot Password' link, primary login CTA with pulse animation, and link to Signup. Connects to JWT authentication API. Redirect to Dashboard on success. Design is already complete — implement from JSX design.
Build Signup Page
As a frontend developer, I want to implement the Signup page based on the existing JSX design (Signup v2) so that new users can create an account. The page includes: name, email, password, confirm password fields, terms acceptance checkbox, primary CTA button, and link to Login. Connects to user registration API. Redirects to Stocks/Dashboard on success. Design is already complete — implement from JSX design.
Implement Portfolio Tracker API
As a backend developer, I want to implement portfolio tracking API endpoints so that users can simulate investments and track P&L. Endpoints: GET /api/portfolio, POST /api/portfolio/investments, DELETE /api/portfolio/investments/{id}, GET /api/portfolio/performance?range=. Compute real-time portfolio value using latest stock prices from cache. Return sector allocation breakdown. JWT auth required.
Build Dashboard Page
As a frontend developer, I want to implement the Dashboard page based on the existing JSX design (Dashboard v2) so that users can view their analytics overview after login. The page includes: TopBar with global search and notifications, Sidebar with nav links (Dashboard, Markets, Portfolio, Watchlist, Analytics, Settings), WelcomeBanner with time-aware greeting and IST clock, MarketOverviewCards (NIFTY 50, SENSEX, Top Gainer, Market Status), PortfolioSummary with donut chart, TrendingStocksTable, WatchlistPanel with flip-card micro-interaction, and RecentActivityFeed. RBAC: Free users see limited analytics with upgrade prompts. Design is already complete — implement from JSX design.
Build Pricing Page
As a frontend developer, I want to implement the Pricing page based on the existing JSX design (Pricing v2) so that users can compare Free vs Premium plans and initiate an upgrade. The page includes: centered headline, two pricing cards (Free with ghost CTA, Premium with glowing orange border, 'Most Popular' badge, INR pricing at ₹499/mo, pulse-glow CTA), feature comparison list with checkmarks, flip-reveal hover on feature items, and 'View Full Pricing' link. Navigated to from Dashboard and Stock Detail. Design is already complete — implement from JSX design.
Build Stocks Listing Page
As a frontend developer, I want to implement the Stocks listing page based on the existing JSX design (Stocks v2) so that users can browse trending NSE/BSE stocks, search by symbol or company name, and view stock prices with % change. The page includes: search bar with autocomplete, segmented tab filters (All, Gainers, Losers, Most Active), sortable data table with color-coded changes, watchlist star toggle per row, and pagination. Row click navigates to Stock Detail page. Design is already complete — implement from JSX design.
Build Checkout Page
As a frontend developer, I want to implement the Checkout page based on the existing JSX design (Checkout v2) so that users can complete payment for Premium subscription. The page includes: order summary card (plan name, price in INR), payment method selection (Razorpay / Stripe), form fields for billing details, secure payment CTA with pulse animation, and success/failure state handling. Navigated to from Pricing page. Design is already complete — implement from JSX design.
Build Watchlist Page
As a frontend developer, I want to implement the Watchlist page based on the existing JSX design (Watchlist v2) so that users can view, manage, and interact with their saved stocks. The page includes: watchlist header with count badge and add-stock button, flip-card stock items (front: price/change, back: 52W high/low/volume), remove button per item, free-user limit prompt with upgrade CTA, premium multi-watchlist tab switcher, and empty state illustration. Design is already complete — implement from JSX design.
Build Admin Page
As a frontend developer, I want to implement the Admin page based on the existing JSX design (Admin v2) so that admins can manage users, roles, and subscriptions. The page includes: admin dashboard with user management table (search, filter by role, edit/delete actions), role assignment UI (Free/Premium/Admin pills), subscription overview panel, and system analytics cards. Access restricted to Admin role via RBAC. Navigated to from Dashboard. Design is already complete — implement from JSX design.
Build Portfolio Page
As a frontend developer, I want to implement the Portfolio page based on the existing JSX design (Portfolio v2) so that users can track their simulated investments, view P&L, and analyze sector allocation. The page includes: PortfolioNavBar, PortfolioHero with breadcrumb and action buttons, PortfolioSidebar with quick-nav, PortfolioSummaryCards (count-up animation), PortfolioPerformanceChart (animated area chart with time-range tabs and benchmark toggle), PortfolioHoldingsTable, PortfolioSectorAllocation (animated doughnut chart), PortfolioTransactionHistory, and PortfolioInsightsBanner. Premium gating on analytics sections. Design is already complete — implement from JSX design.
Integrate Frontend with Payment API
As a frontend developer, I want to integrate the Pricing and Checkout pages with the subscription and payment API so that users can complete a Premium upgrade via Razorpay or Stripe. Implement: plan display from API, Razorpay/Stripe SDK initialization on Checkout page, payment order creation, webhook result handling, success/failure redirect flows, and subscription status reflection across the app (hide upgrade prompts for Premium users).
Build Stock Detail Page
As a frontend developer, I want to implement the Stock Detail page based on the existing JSX design (Stock Detail v2) so that users can view detailed stock information, historical price charts with technical indicators, company details, and market news. The page includes: animated Chart.js candlestick/line chart, time-range selector, technical indicator overlays (RSI, MACD — premium gated), company info panel, news feed, and 'Add to Watchlist' button. Navigated to from Stocks listing and Watchlist pages. Design is already complete — implement from JSX design.
Integrate Frontend with Watchlist API
As a frontend developer, I want to integrate the Watchlist page and Dashboard WatchlistPanel with the backend watchlist API using TanStack Query so that users can add/remove stocks and see their watchlist in real time. Implement optimistic UI updates for add/remove actions. Show free-user limit feedback dynamically based on API response. Sync watchlist star state in Stocks table and Stock Detail page.
Integrate Frontend with Stock APIs
As a frontend developer, I want to integrate the Stocks, Stock Detail, Dashboard, and Portfolio pages with the backend stock data API using TanStack Query so that users see real-time and historical market data. Implement: data fetching hooks for trending stocks, search autocomplete, stock detail + history, portfolio performance chart data. Handle loading skeletons, error states, and cache invalidation. IST timezone display for all timestamps.
No comments yet. Be the first!