# om-mishra7/a-star architecture

> Architecture diagram of the GitHub repository om-mishra7/a-star, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/om-mishra7/a-star
- Repository: https://github.com/om-mishra7/a-star

## Overview

##### Project type and purpose
- This is a monolithic full-stack web application (“A* – Community Competition Platform”) built on Flask.
- It serves dynamic HTML (via Jinja2 templates) and static assets, manages users/contests/problems/submissions, and integrates external services (Judge0, Google Gemini, OAuth2 provider, CDN).

##### File structure
- Root files: Dockerfile, vercel.json, requirements.txt, README.md → deployment and build config.
- backend/main.py → single entry point for routing, controllers, business logic.
- backend/templates/… → Jinja2 views organized by page/function (problems, contests, admin forms, private includes).
- backend/static/… → CSS, JavaScript (including Monaco editor), image assets.
- No separate “models” folder → data-access likely encapsulated in service functions within main.py.

##### Relationships and data flow
- Browser → HTTP(S) → Flask routes:
– Frontend routes return HTML + static assets (templates + CSS/JS).
– AJAX/Fetch calls to backend API (submissions, user-data endpoints).
- Flask ↔ Redis: session read/write and cache common data (announcements, leaderboards).
- Flask ↔ MongoDB: CRUD on users, problems, contests, submissions, leaderboards.
- Flask → OAuth2 Provider: redirect/login callback to exchange code for user info.
- Flask → Judge0 CE API (async code execution):
– POST code, receive token → store submission in MongoDB → poll with token → update status.
- Flask → Google Gemini API: generate problems, reports, user summaries.
- Flask → CDN API: upload/manage profile pictures.

##### Architectural patterns & principles
- Layered (MVC-style):
– Controllers (Flask routes in main.py),
– Views (Jinja2 templates + static),
– Models/Services (data-access + business logic in functions).
- Context processors inject global data into views.
- Middleware (`@after_request`) for headers (caching/static assets).
- Rate limiting & similarity checks in submission flow.

1. Sketch a high-level block for each main component.
4. Inside the Flask block, subdivide by major feature areas: Auth, Submissions, Contests, AI, Context.
6. Review to ensure every external service, datastore, and critical module is represented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers and components
    Browser["User Browser"]:::frontend
    subgraph "Flask App Container" 
        direction TB
        Flask["Flask (WSGI)"]:::backend
        Controllers["Routing & Controllers"]:::backend
        Templates["Jinja2 Templates"]:::backend
        StaticAssets["Static Assets"]:::backend
        subgraph "Service Layer"
            direction TB
            SubmissionProc["Submission Processor"]:::backend
            ContestLogic["Contest Logic"]:::backend
            AIGenerator["AI Generator"]:::backend
            ContextProc["Context Processors"]:::backend
        end
    end

    %% Datastores
    Redis["Redis (v6+)"]:::datastore
    Mongo["MongoDB (v5+)"]:::datastore

    %% External Services
    OAuth2["OAuth2 Provider"]:::external
    Judge0["Judge0 CE API"]:::external
    Gemini["Google Gemini API"]:::external
    CDN["CDN for Profile Pics"]:::external

    %% Infrastructure
    Docker["Dockerfile"]:::infra
    Vercel["vercel.json"]:::infra
    Requirements["requirements.txt"]:::infra

    %% Connections
    Browser -->|HTTPS| Flask
    Browser -->|Fetch/AJAX| Controllers
    Controllers --> Templates
    Controllers --> StaticAssets
    Controllers -->|Session/Cache| Redis
    Controllers -->|CRUD| Mongo
    Controllers -->|Authenticate| OAuth2
    Controllers -->|POST code| Judge0
    Controllers -->|Poll token| Judge0
    Controllers -->|Generate| Gemini
    Controllers -->|Upload| CDN
    Controllers --> SubmissionProc
    Controllers --> ContestLogic
    Controllers --> AIGenerator
    Controllers --> ContextProc

    %% Infra connections
    Docker --> Flask
    Vercel --> Flask
    Requirements --> Flask

    %% Click events
    click StaticAssets "https://github.com/om-mishra7/a-star/tree/main/backend/static/"
    click Templates "https://github.com/om-mishra7/a-star/tree/main/backend/templates/"
    click Flask "https://github.com/om-mishra7/a-star/blob/main/backend/main.py"
    click Docker "https://github.com/om-mishra7/a-star/tree/main/Dockerfile"
    click Vercel "https://github.com/om-mishra7/a-star/blob/main/vercel.json"
    click Requirements "https://github.com/om-mishra7/a-star/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#cccccc,stroke:#333,stroke-width:1px
    classDef backend fill:#83b0e3,stroke:#333,stroke-width:1px
    classDef datastore fill:#a3e083,stroke:#333,stroke-width:1px
    classDef external fill:#e38b83,stroke:#333,stroke-width:1px
    classDef infra fill:#d0d0d0,stroke:#333,stroke-width:1px
```
